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SECTION 7 


By Rich Morin 


Some Basic Commands 


Learn these first; the others can wait! 


Before we look at any specific commands, we need 
to look at some fundamental differences between BSD 
terminal sessions and the ordinary Mac OS X (OSX) 
experience. Each interface has its advantages and 
disadvantages; by understanding these, you 11 be able to 
use both interlaces more effectively! 

* Applications vs. Commands OSX applications tend 
to be highly interactive, providing customized 
environments for accomplishing particular tasks. BSD 
commands, in contrast, are generally run in “batch 
mode”. The user issues the command, giving all of 
the needed information, waits for the result, and 
goes on, 

* Documents vs. Files OSX documents are generally 
encoded in an application-specific data format. 
Consequently, it is only by extra effort that other 
applications can make use of them. BSD files are 
expected to be useful to a wide range of commands. 
As a result, they are often formatted as ASCII text 
files, using white space (blanks, spaces, and 
newlines) to delineate internal daia elements. 

* Subjects vs. Verbs In OSX, the user double-clicks on 
the icon for a document (subject) and the 
appropriate application (verb) starts up. 
Alternatively, s/he drags the document icon (subject) 
over to the application icon (verb). In BSD, the user 
types in the name of a command (verb), followed by 
assorted file names (subjects) and flags (adverbs), 

* Mice vs. Keyboards OSX employs a graphical user 

interface (GUI), using the mouse (trackball,.) for 


nearly every action. Keyboard “shortcuts” are 
provided in some cases, but they are never required. 
In BSD, the situation is exactly reversed. The 
keyboard is used for everything; mouse “shortcuts” 
are used only occasionally. 

* Windows vs. Sessions OSX applications often put up 
multiple windows; actions taken in one window are 
expected to have ramifications in all of the other 
windows. Each BSD terminal session, in contrast, is 
expected to be independent of all of the other sessions. 

* Aqua vs. The Shell Aqua (including the Dock and 
the Finder) allows the user to navigate through the 
file system, manipulate documents and folders, and 
start up commands. The BSD “shell” (assisted by 
some common commands) provides equivalent 
capabilities, plus others (e.g,, scripting, session 
logging). Of course, the user interfaces vary 
substantially! 

Navigation Commands 

As noted above, BSD command lines start with a 
verb, followed by some number of subjects and adverbs. 
Last month, we used the ' man” command to view 
manual pages; let's use it again, trying out some 
variations. 

[ 1 Qcalbosti~] rdm% man 2 sync 
[localhost:rdm% man 8 sync 
[localhostrdml man sync 

The sync{2) manual page describes a system call; 
sync(8), in contrast, is a system maintenance command. 
By specifying the section number, we can tell man 
which part of the manual to search. In most cases, there 
is no conflict, so the section number can be left off. 


Rich Morin has been using computers since 1970, Unix since 1986, and Mac-based Unix since 1986 (when he helped Apple create A/UX TO). When 
he isn’t writing this column. Rich runs Prime Time Freeware (WWW.ptf.COfn), a publisher of books and CD-ROMs for the Free and Open Source software 
community. Feel free to tvrire to Rich at rdm@ptf.com. 


Some Basic Commands 


MacTech * * June 2002 










None of man’s “arguments" are actually file names. 
Instead, they are hints that allow man to search assorted 
directories* The actual list of directories that man 
examines is specified by MAN PATH, a BSD 
“environment variable’ 1 . Environment variables and 
control files perform many of the functions of OSX 
preferences: 

riocalhoBt:-] rdm% echo $MANFATH 

/Users/rdm/man;/usr/local/share/man:/usr/share/man 

This tells us that man looks first under 
/Users/rdm/man (the user’s personal man pages), 
/usr/local/share/man (this machine's “local" man 
pages), and /usr/share/man (OSX man pages). Lets 
wander over to the latter directory and take a look: 

[ iocalhost:“] rdm% cd /usr/share/man 
[localhost:/usr/share/man] rdm% Is -F 
ma.nl/ man3/ man5/ man?/ 

whatis * db 

man2/ man4/ man6/ manS/ 

The cd(l) command sets /usr/share/man as the 
“current directory" for this terminal session. This can 
save a lot of typing! For convenience, the shell puts the 
name of the current directory in the command line’s 
“prompt string". 

The ls(1) command provides a directory listing, 
appending slashes to directory names (as directed by 
the -F option). So far, the Finder seems a lot more 
convenient, but hang on a bit! Let’s find out which 
directories have “sync" man pages: 

[ localhost:/usr/share/man] rdm% la */flync* 
man2/sync.2 man8/sync.8 

The asterisk "wild cards" tell the shell to look 
through every subdirectory, looking for files whose 
names begin with “sync". Hmm; looks like the shell has 
some advantages when lots of items are involved. How 
many pages might that be, anyway? 

[localhost:/usr/share/man] rdm% Is */• j wc -1 

2353 

This command “pipeline" ran two commands, 
directing the “standard output" of one into the “standard 
input" of the other. The first command listed every file 
in every subdirectory; the second counted the number 
of lines in the first command's output. The result (2853) 
was something which neither base command was 
“designed" to produce. 

This pipeline is actually a minuscule instance of a 
“shell script". BSD users frequently write scripts to 
automate repetitive tasks. Next month, we'll look at 
some more commands and some fancier ways of writing 
shell scripts. 
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SCRIPTING 


By Paul Ammann 


Shell Scripts, Perl and Python 


In the early days computers where used to run 
programs, and nothing more. You punched your program on 
cards, delivered the pack to the computer department. The 
staff there loaded the program into the computer, executed it 
and retrieved the result on paper. This was in turn returned 
to you and you had to sit down and figure out why you got 
(he result you got. 

Modern computers are a little more complex than that. 
You have a complete environment where you can execute 
your programs and even have such astonishing things as 
interactive programs. It is no longer enough to he able to 
load your program and just print the result. You also need 
support to reformat the results, process them in other 
manners (maybe printing a nice diagram) and store them in 
a database, it would of course be possible to write specially 
designed programs that formatted the output of your 
programs according to your wishes, but the number of 
specialized programs would quickly increase, leaving your 
computer loaded with "might come in handy 11 programs. 

A better approach would be to have a small set of 
processing programs with a program made to "glue the parts 
together/ On a UNIX system, such a program is called the 
shell* The shell is used to issue commands, start processes, 
control jobs, redirect input and output, and other mundane 
things that you do on a modern computer. Not only that, the 
shell is a pretty complete programming language. 

Now that Apple has switch to UNIX-based operating 
system, there are several new languages users can utilize: the 
Shell script, Peri, and Python, In this article we introduce 
each of languages, provides some insightful information 
about each one, and point out useful resources for readers. 

The Basic Shells 

The basic UNIX shells come in three main language 
forms. These are and in order of creation; Bourne Shell, C 
Shell, and the Korne Shell), be aware that there are several 
dialects of these script languages, which tend to make them all 
slightly platform specific. The different dialects are due, in the 
main, to the different UNIX flavors in use on some platforms. 


All script languages though have at their heart a common core, 
which if used correctly will guarantee portability. 

Why use Shells? There are three reasons; Cl) ft is the 
simplest way to string a bunch of UNIX commands for 
execution at any time without the need for prior compilation; 
(2) It’s generally fast to get a script going, not forgetting the 
ease with which other scripters can read the code and 
understand what is happening; and (3) they are generally 
completely portable across the whole UNIX world, as long as 
they have been written to a common standard. 

The Bourne Shell 

Historically the Bourne shell language, or sh f was the 
first to be created, li has a very compact syntax, which makes 
it obtuse for novice users but very efficient when used by 
experts. It also contains some power constructs built in. On 
UNIX systems, most of the scripts used to start and configure 
the operating system are written in the Bourne shell. It has 
been around for so long that is it virtually bug free. 

The C Shell 

Next up is the C Shell, or esh, so called because of the 
similar syntactical structures to the C language. The UNIX 
man pages contain almost twice as much information for the 
C Shell as the pages for the Bourne shell, leading most users 
to believe that it is twice as good. This is a shame because 
there are several compromises within the C shell, which 
makes using the language for serious work difficult (check 
the list of bugs at the end of the man pages!). True, there are 
so many functions available within the C Shell that if one 
should fail another could be found. The point is do you realty 
want to spend your time finding all the alternative ways of 
doing the same thing just to keep yourself out of trouble. The 
real reason why the C Shell is so popular Is that it is usually 
selected as the default login shell for most users. The features 
that guarantee its continued use in this area are aliases, and 
history lists. 


Paul Ammann works as Network Security Engineer for a logistics company in Connecticut, He was l>een working with UNIX and Linux for the last S 
years When not working, he is busy working on his Nokia Firewall Manager project, or plotting Lhe next vacation adventure with his wife Eve, He 
can he reached at amani@users.sourcefoige.net 
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The Korne Shell 

Lastly, we come to the Korne Shell, or ksh. made 
famous by IBM's AIX flavor of UNIX, The Korne shell can be 
thought of as a superset of the Bourne shell as it contains the 
whole of the Bourne shell world within its own syntax rules. 
The extensions over and above the Bourne shell exceed even 
the level of functionality available within the C shell (but 
without any of the compromises!), making it the obvious 
language of choice for real scripters. 

What is a Shell Script Anyway? 

A shell script, in its most basic form, is simply a collection 
of operating system commands put into a text file in the order 
they are needed for execution. Using any of die shell 
mentioned so far, a text file containing the commands listed in 
Example I would work every time the script was executed. 

Code L Basic shell script 

fjM /bin /sh 

ttn -f /ttnp/listing. trap ) /dev/null 25&1 
touch / trap/list ina. tmp 

Ls 1 [a z]*.doc I sort ) /ttnp/listing*trap 
Ipr Ppostscript_1 /trap/listing,trap 
rm -f /imp/listing.tmp 

Of course nut all scripts are this simple but it shows that 
ordinary UNIX commands can be used without any extra, 
fancy scripting constructs. If this script was executed any 
number of times the result would the same, a Song listing of 
all the files starting with lower case letters anti ending with 
a doc extension from the current directory printed on your 
local PostScript printer. 

If Shell scripting isn't for you, there arc two other 
languages to consider: Perl and Python. Both languages arc 
similar in functionality, However, in terms of syntax, they are 
as different as night and day hi the next section, we’ll take 
a close look at both of these languages, and develop UNIX 
daemon that will demonstrate the same functionality and the 
contrast of syntax. 

Perl vs* Python 

Perl is a language optimized for scanning arbitrary text 
files, extracting information from those text files, and 
printing reports based on that information. It’s also a good 
language for many system management tasks. The language 
is intended to he practical (i,e., easy to use, efficient, 
complete) rather than beautiful 

Perl combines some of the best features of C, sed, awk. 
and sh, so people familiar with those languages should have 
little difficulty with it. Expression syntax corresponds closely 
to C expression syntax. Unlike most UNIX utilities, Perl does 
not arbitrarily limit the size of your data— if you have the 
memory, Perl can slurp in your whole file as a single string. 
Recursion is of unlimited depth. In addition, the tables used 
by hashes grow as necessary to prevent degraded 
performance. Perl can use sophisticated pattern matching 
techniques to scan large amounts of data quickly. 


On the other hand, Python is simple to use, and it's more 
of a real programming language, offering much more 
structure and support for large programs. It also offers much 
more error checking than C, and, being a very high-level 
language, it has high-level data types built in. such as 
flexible arrays and dictionaries that would cost you days to 
implement efficiently in C. Because of its more general data 
types, Python is applicable to much larger problem domain 
than awk or even Perl 

Python allows writing very compact readable programs. 
This is do to the fact that statement grouping is done by 
indentation instead of begin/end brackets. Like Perl, Python 
is an interpreted language; however, Python is an object- 
oriented language like C++ but without the headaches of 
constructors or destructors. 

I could go on and on about Perl and Python. However, 
I’ll let the code speak for itself, 

Writing a UNIX Daemon In Perl and Python 

The word daemon is derived from the Greek word 
daimon, meaning “a supernatural being” or 'spirit", rather 
than demon, referring to the fallen angels or followers of 
Satan. Some would insist that UNIX is infested with both 
daemons and demons, In UNIX, daemons are typically started 
by the root process when the operating system is initialized, 
and run in the background indefinitely. Daemons typically 
spend most of their time waiting for an event or period when 
they will perform some task, 

UNIX Processes 

Before we explore the details of what a daemon is, let’s 
review the characteristics of a UNIX process, hirst, let’s take 
a look at a partial process list: 


> ps astu 

PPID PID 

PGID 

SID TTY 

TPGID 

STAT DID TIME 

COMMAND 

0 1 

0 

0 7 

-1 S 

0 

0:03 

init 

1 2 

1 

1 7 

-1 5W 

0 

0:00 

[kflushd j 

1 3 

1 

1 ? 

-1 SW 

0 

0:00 

[kpiod] 

1 4 

i 

1 7 

1 sw 

0 

0:00 

[kswapd] 

1 548 

548 

548 ? 

-1 s 

0 

0:00 

httpd 

548 557 

548 

548 ? 

■1 s 

99 

0:00 

httpd 

548 538 

548 

548 7 

-1 s 

99 

0:00 

httpd 

548 559 

548 

548 ? 

-1 s 

99 

0:00 

httpd 

548 560 

548 

548 ? 

-1 s 

99 

0:00 

httpd 

548 561 

548 

543 7 

-1 s 

99 

0:00 

httpd 

543 562 

548 

548 7 

1 s 

99 

0:00 

httpd 

543 563 

543 

548 7 

-1 S 

99 

0:00 

httpd 

2450 2452 

2452 

2452 pts/5 

25 76 S 

501 

0:00 

zsh 
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The first column is the parent process id, the process id 
of the process that created it, The second column contains 
the process id, which is assigned by the kernel. The next 
column is the process group id. The fourth column is the 
session id, A session is a collection of session groups. The 
next column contains the tty, or controlling terminal, that’s 
related to the process. This is typically a terminal or remote 
login shell. 

Daemon Rules 

There are several rules or characteristics that most 
daemons possess. If a daemon does not follow these basic 
rules, it will most likely become a demon and wreak havoc 
on your system, 

Fork and Exit 

The first thing a daemon should do is fotkQ a child 
process and have the parent process exit(). This is necessary 
for several reasons. First, it disassociates the process from the 
controlling terminal, or the login shell. Second, it removes 
the process from the process group that initiated the 
program. This ensures that the process is not a process group 
leader, which is required for setsidQ to run successfully. 

Call setidQ 

setsldO is ^ POSIX function that turns the process inLo 
a session leader, group leader, and ensures that it doesn’t 
have a controlling terminal. 

Change Working Directory 

The current working directory should be changed with 
chdir to the root directory (/), This is necessary to avoid 
using a working directory that resides on a mounted 
partition. If the process is started on a mounted partition, the 
system administrator wouldn't be able to unmount the 
partition until the process was halted. You could specify a 
different working directory as long as it doesn’t reside on a 
remotely mounted partition. 

File Creation Mode 

The umask determines the default permissions new files 
are assigned. Setting umask to 0 removes the defaults that 
might otherwise disable permissions the daemon intended to 
enable when creating files. 

Close Unneeded File Handles 

Besides dosing any filehandles that might have been 
Opened, daemons often redirect 5TDIN to read from, and 
STD OUT and STD ERR to write to /dev/null 

Cock Example 2. Redirecting STDIN, STDOUT and STDERR in Perl 

open STDIN, */dev/null V; 
open STDOUT. ^/dev/null’ : 
open STDERR, ’>/dev/null r ; 

Code Example 3 Redirecting STDIN, STDOUT and STDERR in Python 

sys.stdout " open(“/dev/null" , ’w’) 

fiyn.stderr = open(“/dev/null*’. 1 w‘) 

sys.stdin = open U*/dev /null”, ‘r’) 
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Logging Messages 

In some eases, you may want to record an error or 
message to a Jog file on the system This can be 
accomplished by redirecting STDOUT and STD ERR to one or 
more log files. 

Code Example 4, Redirecting STDOUT and STD ERR to one or more log files in 
Perl 

open STDOUT, ">>$access_log" or die "Can't write to 
$access_log: $ I”; 

open STDERR, ">>$error_log* or die "Can't write to 
$error_log: $!": 

Code Example 5. Redirecting STDOUT and STDERR to one or more log files in 
Python 

try: 

sys.stdout - open{' i >>access_log", ’w 1 ) 
except: 

print "Can't write to access_log” 

try: 

sys,stderr - open [">>error log H , *w') 
except: 

print "Can’t write to error_log" 


Writing the Daemon 

Now that we understand the basic attributes of a 
daemon, let’s put the pieces together into a simple 
Perl/Python program. 

Code Example 6. Simple Daemon in Perl 

jn/usx/fainVenv perl 

# load required modules 

use strict: 

use POSIX qw(setsid); 

chdir or die "Can't chdit to /: $[”; 

umask 0; 

open STEIN, ‘/dev/null’ or die "Can't read /dev/null: 

if open STDOUT, * ? /dev/null ' or die “Can't write to 
/dev/null: $! M : 

open STDERR. '^/dev/null’ or die "Can’t write to 
/dev/null: $!": 

defined(my $pid = fork) or die “Can't fork: $]**': 
exit if $pid; 

setsid or die "Can’t start a new 

session: $3 M : 

vh 11e (1) \ 
sleep(5) ; 

print “Hello,**\n": 


('ode Example 7. Simple Daemon in Python 

in/usr/bin/env python 

import os, sys. time 

os h chdir("/") 
os.umask(D) 

try: 

sys.stdout = open("/dev/null", 'w') 
except: 

print "Can't read /dev/null" 

try: 

it sys.stderr = open (“ / dev/nul 1”, 'w' ] 

pass 
except: 

print "Can’t write to /dev/null" 

try: 

sys.stdin — open("/dev/null”, ‘r’) 
except: 

print “Can't write to /dev/null" 


try: 

pid — os,fork 0 
except: 

print "Can’t fork” 
if pid: 

sys,exit(1} 

try: 

os*setsid[) 
except: 

print "Can't start a new session" 

while £ 1): 

time.sleep(5) 

print "Hello... M 

Code Examples 6 and 7 are a simple daemon that will 
print Hello... to the console every five seconds. Also, 
looking at both examples, notice that ihe line of the program 
has been commented out. Removing the comment will 
suppress the hello message by sending all standard output to 
/dev/null. Also, notice that we included the POSIX library 
and explicitly imported the setsid function since this 
function is part of the POSIX library, not a built-in Perl 
function. One other little critical piece is the while(l) ( 1 
loop with sleep(5) inside. The loop ensures that the script 
will run indefinitely. The sleep function sets the number of 
seconds between each iteration in the loop. The main body 
of your code will site inside this while loop. 

In this brief tutorial, we learned how to create a robust 
daemon in both Perl and Python for most any UNIX system. 
Which language is better? I don't know. Per! has been around 
since 1993 anti there is a treasure chest of source code 
available for it. However, there is nothing to stop you from 
porting Perl code over to Python, just a few minor changes. 

Resources 

For readers who are interested in learning more about Shell 
programming, I can highly recommend UNIX Shell Programming 
by Stephen G. Kochan and Patrick H Wood. I keep one copy at 
home, and one at work, In addition, check out 1 leaner Stevens 
web site SHELLdorado (http://www.shelldorado.conn/) and Sun 
Microsystems has a very resourceful web site 
(http://www.sun.coni/bigadnnin/scripts/index.html). 

If you are interested in getting your feel with Perl. Learning 
Perl by Randal L. Schwartz and Tom Phoenix is my pick. By the 
time you've finished this book, you will know if Perl is the right 
language for you without making a huge investment. For me, 
Core Python Programming by Wesley J, Chun was the book that 
converted me from Perl. Enough said. 

Regardless if you choose Perl or Python, check out 
Active State, which make IDE programs for both languages 
and has a large library of code for beginners 
(http://aspn.activestate.com/AS PN/Cookbook/). If you decide to 
write a major application with either, I would recommend 
wxPerl (http://wxperl.sourceforge.net/) and wxPython 
(http://wxpython.org/). Both software libraries are derivates of 
wxWindows (http://www.wxwindows.org), which is a free C++ 
framework to make cross-platform programming child's play. 
Well, almost. Enjoy! 
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By John C. Welch 


Heterogeneous Networks as a Defense 
Mechanism 


Why a genetically diverse network has 
advantages that a network of clones 
can’t match 


Welcome 

Crackers, Viral attacks. Inside attacks The computing world 
is fraught with peril these days. Yet as much as we would like to 
hide away from these things or ignore them, we have to deal 
with computers, computer networks, and the security and 
privacy issues they bring. Hut the question is always, how do we 
counter all the bad things in the computing world so that we can 
get to work? There are quite a few methods, some more 
common than others, none of which are a panacea. The most 
used methods are prophylactic, or external defenses/protections, 
and while they have achieved a certain amount of success, such 
measures, in the end, guarantee a certain amount of failure as 
well, 

External Defenses and associated issues 

The way most people defend their networks and computers 
are by creating barriers to external attacks. For example, to 
defend against virii, we buy antivirus applications. We use 
firewalls to prevent crackers from gaining access. We use arcane 
password requirements and policies, and stringent policing of 
interna! network usage to keep employees and other authorized 
users from causing damage. More concisely, we use prophylactic 
hardware, software, etc. Now. I’m not going to say these are bad, 
or unnecessary actions. In fact, they are quite intelligent actions. 
But, as we will see, on their own, they are not ever going to be 
enough. 

Problems 

Virii 

Virus defense is a particularly thorny issue. In the last few' 
years, you’ve gone from only having to update viruses monthly, to 
daily updates. You have to scan almost every file that you 
download or use, and you have to repeatedly scan the same files, 


because virus waiters get smarter all the time. Viruses are also 
becoming smarter, or at least more flexible in design and execution 
They change their code each time they run, they dance from sector 
to sector of the drive, some will even dodge virus scans. 

Ifs not even an operating system issue any more. 
Application - based virii have surpassed operating system virii 
in number and infection rates. It’s also not just a Microsoft 
application issue. QuickTime, Adobe Acrobat, and other 
applications from different vendors are being infected. 
Services are getting slammed the same way. IIS, and other 
Well/Internet services are being used as viral delivery 
mechanisms. While tilings like US attacks are limited to a 
single operating system, the way services like IIS work means 
that the virii that target them can also hurt non-Windows 
services by creating a denial of service, (DOS) attack situation 
as they probe Apache, iPlanet. WebSTAR, and other Web 
Service Servers looking for a valid entry point, 

Unfortunately, die image of a virus creator as some 
demented savant with no social skills sitting alone in the dark 
wreaking havoc on a cruel world is absolutely incorrect. There 
are now virus kits’ on the Internet that allow anyone who can 
work a GUI to create virii that are quite advanced in nature 
while possessing only minimal technical abilities. The 
Kournikova virus is an example. The creator of this Microsoft 
Outlook virus was not a cracker, or any other kind of 
programmer. He wasn’t a computer expert of any kind. He was 
an Anna Kournikova fan who wanted to spread her fame. The 
method he chose, while damaging and annoying, was the 
modern version of Led Zeppelin fans in the 1970s spray - 
painting l Zo/o* on bridges and highway overpasses. So almost 
anyone with Internet access can create viruses. 

While antivirus vendors have done an admirable job, with 
on the fly scanners, email attachment scanning, server scanning, 
heuristic analysis, (which looks lor virus - like behavior as 
opposed to static signatures’), there is still a problem with 
relying on antivirus utilities as the sole form of protection. Delay. 
There is always a delay between the discovery of the virus and 
the release of the inoculation definitions. As well, there is a delay 
between the announcement of the release and the downloading 
and vaccination of infected systems. There is also the delays in 


John Welch <jwelcli@mit.edu> is the IT manager for the MIT Police department, and the Chief Know-It-All for Tacky Shirt. He has over fifteen years 
of experience at making computers work. John specializes in figuring out ways in which to make the Mac do what nobody thinks it can, showing 
that the Mac is the superior administrative platform, and teaching others how to use ii in interesting, if sometimes frightening ways. He also does tilings 
that don't involve compufertry on occasion, or at least that's the rumor. 
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release times between different antivirus vendors of new 
definitions. In the case of a vims like Code Red, which spread 
at amazingly high speeds, this means that network 
administrators have to shut down vulnerable systems until the 
systems can be cleaned. Widi Code Red, this meant shutting 
down entire networks. Clearly, the measure - countermeasure - 
counter-countermeasure dance of vims and anti vims is not a 
winning strategy* (This should in no way be interpreted as 
saying that antiviral utilities are not worth the effort. Any security 
and protection plan should be layered, and antiviral utilities are 
a critical part of at least one of those layers. Even on platforms 
with a normally low rate of infection* if there is an antiviral utility 
available, and you aren't using it because 'you never see <my 
piatform> being infected, that just happens to <some other 
platform>, then you are, to put it nicely, deluding yourself*) 

Security and crackers 

Non-viral attack points are everywliere as well. The recent 
announcements of vulnerabilities in SNMP and PHP affect any 
operating system that can run these services, (which is almost all 
of them, and in the case of SNMP, includes non - Mac OS X Macs.) 
Security holes are endemic on all platforms, even if they don't get 
the same level of publicity as the Microsoft security holes* 

While all of these holes can be patched, there ts the same 
delay as with virii* The vendor has to be notified of 
vulnerabilities, the vulnerability has to be analyzed, fixed, the fix 
tested, and distributed. In some cases, the patch creates other 
problems which have to go through the notification-analysis-fix- 
fix test-fix distribution cycle. Meanwhile, crackers are able to use 
these holes to break into systems and at very least, increase an 
already overburdened IT department's workload, which almost 
ensures Lhat mistakes will be made in patch implementation, 
creating situations where systems that aren't patched are thought 
to be patched, and are now 'stealth holes' inu> a network. 

A major problem with defending against crackers in Lhis 
manner is one that you can't patch or secure against, and that is 
the attitude that the non-IT world takes towards them. For the 
most part, they are either viewed as misguided, or crusaders 
helping overworked, or (more commonly) inept IT people secure 
their networks. Because people don’t think of computer data as 
'real' and rime has never been seen to have an inherent cost in 
IT, since we are all paid on salary, the time that these criminals 
take from IT people is seen as the IT person's just reward for not 
doing their jobs correctly. One cracker, Adrian La mo, has gained 
a measure of fame as a Security crusader’ by breaking into 
systems, changing data, then informing the owners of die system 
of Iris attack, then offering his services to fix the holes. 

Now 1 ,1 think that any intelligent network administrator will, 
Lit some point, hire someone to try and penetrate their security. 
That is the only way to ensure that you have done tilings 
correctly. But the important thing here is that the people tunning 
the attacks have been hired for that purpose. If someone cracks 
your network* without being authorized to do so, then there is 
a more precise term for their actions: Breaking and Entering. 


I am completely serious about this. If you came home, and 
found someone sitting in your Barcalounger watching your TV, 
drinking your beer, and they told you that they had broken into 
your home to show you how had your security is, and they’ll 
happily fix that for you if you hire them as a security consultant, 
you would first laugh at them, then call the cops. There is no 
difference save the physicality of the house break in. But 
because computers aren't Teal' then breaking into one Isn't a 
’crime' in most people’s eyes. That attitude needs to be changed. 
Professionals don’t break into my systems if they want me to hire 
them. They come to me and offer their services* If I accept, dien 
they try to find my security holes, and help me dose them. If I 
don’t accept, then they go away except for annoying sales calls, 
if I get a visitor telling me how they broke into my network, and 
offering their services so it can't happen again, the first thing I’m 
doing is calling the cops, The second thing I'm doing is hiring a 
professional security consultant to work with me to patch these 
holes. If nothing else, am I seriously supposed to professionally 
trust someone who uses a lack of ethics as a sales tool? 

But increased security isn't the Tiber-fix’ that people think it 
is either. In some cases, security can create it’s own problems if 
applied incorrectly, Overzeaious security policies applied 
without thought to their effects on the people lhat have to live 
with them can make daily use of computer resources SO difficult 
that employees feel they have to find ways around them just to 
get work done. Email scanning for dangerous payloads is often 
used as an excuse to scan email content for Inappropriate 
content', which is defined so nebulously that employees feel the 
need to use non-company email accounts while at work, which 
creates more security holes that have to be patched, and still 
more onerous security policies. 

One of the sillier side effects of the viral problems that gets 
passed off as security is the severe restriction or even banning of 
entail attachments. This is not just an IS policy issue. One of 
Microsoft’s first anti viral Outlook updates essentially made it 
impossible to use attachments with Outlcxjk. Obviously this is 
not a sane answer. Attachments make email far more useful than 
it could otherwise be. Yes, they can be misused, but so can 
HTML email, and no one seems to be stalling a trend to ban that. 
If you restrict email to the point where no one wants to use it, 
then you are just killing a critical tool to avoid a problem that 
you will end up with anyway* 

Remember that in general, the more secure a system is, the 
harder it is to use. This is particularly evident wTien you see 
companies implementing physical security policies like 
removing floppy / CD drives, or placing locks on them so that 
you can't casually use them. While a company is perfectly in the 
legal right to do this, such a serious indication that the 
employees can’t f>e trusted is never a good policy unless you 
have other security requirements that require you to do this. 

So security is even more of a balancing act than antivirus 
defenses are. If you go too far. the system becomes unusable* If 
you don’t go far enough, then you are under attack constantly, 
by your own machines in many cases. 
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Human issues 

These are not only the most complex, but they will also 
cause you the most problems if not dealt with correctly. First, 
you have user training. If you do not train the people on the 
network correctly and hold them accountable to that training, 
then you don't have a prayer of any other external protections 
working. But there are inherent problems that crop up 
constantly with the user training solutions. 

Training isn't cheap. ExLemal training can cost from a 
couple of hundred to a couple of thousand dollars per person 
per course. This can get prohibitively expeasive for larger 
corporations. In house trainers may lx* cheaper, but what 
department wants to have to deal with that headache and 
expense. You still need facilities, equipment, lesson plans, 
courseware, study materials, etc. As well, the first budget to be 
cut, and the last to be restored is always the training budget. So 
what ends up happening is a new' employee gets a list of Don'ts’ 
that they read just enough to find the part where they are 
supposed to sign, acknowledging that they have indeed 
absorbed these important items into the very Fiber of their being, 
hand it back to their boss, or HR, and then forget it ever existed. 
Training could be one of the best defenses against network 
break-ins and viral attacks, but not until it is seen as being as 
critical as power, water, and the CKO's bonus. 

While eliminating training of the general user population 
seems as ignorant and short - sited as it is, it pales to the way 
that most corporations treat the people tasked with keeping the 
network safe and running efficiently, IT departments will be told 
that they are critical to a company's operations, then get their 
budgets slashed due to reasons from the economy to the CEO 
hearing from a golf partner that outsourcing will save him more 
money than the company makes in a year. The IT staff has to 
deal w ith every facet of a network and all attached devices, yet 
they get no more of a training budget than anyone else, namely 
none. In addition, since they are usually looked at as a drain on 
the company's bottom line, their requests lor additional funding 
get analyzed more than almost any other department, 

IT departments are perennially short - staffed, even as their 
workload increases yearly, monthly, sometimes daily. 
Companies tell you up front that you gel paid for 40 hours, but 
the minimum work week is 60 hours, with mandatory overtime. 
If you try to do your job in eight hours and go home, you are 
seen as riot a team player’, and let go at the first opportunity. 
The problem this creates is high turnover rates, with some 
companies replacing entire departments every couple of years 
when the numbers are averaged out. As a result, there is almost 
no 'institutional' memory in corporate IT departments, because 
that requires that your senior IT staffer not be the only one to 
have been diere for over a year. 

Ideally, the IT people will document what they do, so that 
when they are gone, there is a history of what has been done to 
and with the network. The reality is that when you are as 
overworked as most IT people are, documentation never even 
enters the picture, much Less actually getting done. So every' time 
an IT person leaves, that knowledge is gone, and has to be 


relearned by the next person, who then leaves, and the cycle 
continues. Some companies are trying to do something about 
this, but they are too few', and still too far ahead of the curve for 
it to become standard practice. 

What this means is that you cannot always rely on having 
an IT staff that is intimately familiar with your network, 
because chances are they either haven't been employed long 
enough to have achieved that level of knowledge, or are on the 
way out, and no longer care. 

End results 

The end results of these factors is that prophylactic 
protection, because of inherent implementation issues, useless 
training initiatives, and IT staff turnover, simply cannot work on 
their own. But there Is another cause that accelerates these 
results, and it is genetic in nature. 

Network homogeneity Is a root enabler for network 

VULNERABILTY 

Almost any article on increasing your IT efficiency, 
improving your KOI. decreasing IT expenditures, making your 
network easier to manage and protect will eventually 
recommend that you take, among any other human or computer 
actions, the step of standardizing your computing platforms on 
a single client and server platform. 1 propose that regardless of 
what platform you settle on, that by making your network 
completely, or almost completely homogenous, that you are 
creating vulnerabilities that no amount of protection can fix. 

The best examples of this are in the non-computing world. 
Human and animal diseases spread fastest when there is a 
degree of genetic uniformity among the species being attacked. 
It is w r ell known among animal and plant breeders that any 
group that is too inbred is vulnerable to diseases and conditions 
than a group with a more diverse genetic background. The 
histories of plant infestations demonstrate how a single species 
can be nearly destroyed within a relatively short time by a single 
disease. The Irish famine of earlier centuries is a rather extreme 
example of this. The potato crops in Ireland were nearly 
destroyed by a blight, which, due to the almost total dependence 
on that plant by the Irish people, caused a massive Famine, 

Ollier examples of the ways that excessive genetic 
similarity creates problems are the conditions and diseases 
that only affect certain groups of people, or affect only 
certain groups in any kind of number, such as sickle-cell 
anemia. This example can easily be applied to network 
design and implementation. 

If you have a network that is all, or mostly homogenous, 
then a new virus has a guaranteed population to infect and 
spread itself from. A homogenous network with high-speed 
connections, and heavy traffic spread virii at astounding rates 
before the infection is discovered and dealt with. Melissa, Code 
Red, Koumikova, and the rest are perfect examples of this. The 
world - wide rate-of Code Red infection should have been a 
wake up call, and it was, but only lately is It becoming the right 
kind of wake up call. 
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No matter how good your defenses, if your network is 
nothing but a series of clones, then they all have exactly the 
same weaknesses to virii, or crackers. This has nothing to do 
w ith platform. An all - Sun, or all - Mac OS X network is just as 
vulnerable to a Sun or Mac OS X - specific attack as an all 
Windows network is to something like Code Red, or Melissa, 
Because tire virii or attacker only has to deal with a single set of 
possible entry points, the job of the cracker or virus creator is 
greatly simplified. All they have to do is construct the virus or 
attack around a given platform's weaknesses, and they are 
assured of at least early success. If the people breaking into your 
network, or writing virii are actually talented or skilled, they can 
use that target specificity to make avoiding detection even easier. 
If all you have to deal with is Windows, or Solaris, or HP-UX, 
then you have a much better chance of avoiding detection 
simply because the conditions you have to deal with are 
drastically reduced. Popularity of platform, not quality of 
platform is why most virii center on Windows. 

We don't, (for the most part), approve of cloning for humans 
or domesticated animals, so why do we not only approve of it 
for computing, but champion it as the answer to all our 
problems? If genetic homogeneity is a threat to well - being 
everywhere outside of computers, how can any intelligent person 
think that those problems magically disappear just because it s a 
computer? IPs not just computers where this falls down. If the US 
Air Force consisted of nothing but F-16s and B-lBs, then 
defeating the U5AF in battle goes from an extremely difficult goal 
to one that is relatively simple. The level of homogeneity that 
exists in some computer networks would be thought of as either 
illegal or the height of stupidity in any other area, so why 
continue to use a method that is so obviously flawed? 

Money spells it out quite well. By having single sources for 
hardware, software, and service, your up front costs for a 
computing environment are greatly reduced. Regardless of 
platform, if everything comes from one place, you save money, 
initially. Up front costs are also the most obvious. I low do you 
show that you saved money because something didn't happen? 
You almost can’t, short of letting the attack or infection happen, 
tallying the costs, and using that as justification lor implementing 
diversity. While this would clearly show the hidden costs of over 
- homogenizing your network, the lack of ethics inherent in such 
an action would, and should get the people involved in such an 
action fired, if not arrested and sued, To pul il bluntly, you cannot 
really show the cost of something that didn't happen. The best 
you can do is use the misfortune of others as your justification. 

Genetic diversity in networks as a strength against 

ATTACK 

So, how do you go about implementing genetic diversity on 
your network? You have to correctly analyze your needs. Too 
many IT divisions get suckered into using the preferred platform 
as the basis for determining network implementation. If you 
look at everything from the standpoint of "How do we get 
<Windows/Solaris/Mac OS X/A1X> to fix this problem, you’re 


already doomed. The platform has to be determined by the 
solution, not vice - versa. (This is not to say that you will never 
have a need for limited amounts of homogeneity. If you have a 
group of people that are writing Windows drivers, then 
obviously they need to have Windows computers. Anything else 
would be inane, ) 

Define the problem correctly 

Rather than think about it from the platform, think about the 
problem on its own. What is the problem? We need faster file 
servers? We need better network management? Define the 
problem on its own. The need for faster file servers has nothing 
to do with Windows or Linux, unless Lite current servers are 
running those operating systems. Even then, that should only be 
an historical note. At this stage, no platform should be excluded 
from consideration. 

Advantages 

The advantages of correct problem definition are numerous. 
First, you can avoid going for the quick solution that may only 
mask the problem. I have seen problems with speed that are 
really caused by an overburdened infrastructure get patched by 
adding servers so that each server has less work to do. The 
infrastructure is still overburdened, but the problem is hidden 
because the individual servers are more lightly loaded. 

Another advantage is that you often find the problem is not 
nearly as complex as it initially seemed. For example, there was 
a company with a normally reliable 16Mbps Token Ring network 
that one day started to go down almost constantly with no 
apparent reason. One of the first proposals was to yank out all 
the Token Ring infrastructure and replace it with Ethernet. 
Luckily the expense that this solution entailed kept it from being 
immediately implemented. What the problem turned out to be 
were unlabeled jacks, It seems the company had recently 
upgraded the number of network drops, and each faceplate had 
two network drops, along with a phone jack, but the labeling of 
the jacks had been put off for last, so the jacks could be installed 
marginally faster. Both the phone system and the Token Ring 
connectors were RJ - type connectors, the phones using RJ-11 
connectors, and the Token Ring cables using Rj-45 connectors. 
So, a single user, not realizing the difference, plugged the phone 
into the Token Ring port. There was just enough contact 
between the connectors in the plug and the cable so that the net 
result was the network was going down, seemingly without 
cause. The correct solution ended up being essentially free, and 
far less traumatic than a complete infrastructure replacement 
would have been. 

So defining the problem correctly, without preconceived 
solutions is critical to correctly implementing a genetically 
diverse network. 

Analyze every possible solution 

So you have defined the problem. Next, see what the 
possible solutions are Platform should still not be a factor here. 
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You need to look at all possible solutions for appropriateness 
dial is not specific to any platform, in our file server speed 
solution, a possible solution may lx? to give all users 100GB 
UltraSC SI RAID stacks on their desks. However, this is 
impractical for many reasons, none of which have to do with the 
platform on the user's desk. But all the solutions need to be 
looked at. There are too many instances of unconventional 
solutions turning out to be the perfect solution for a problem. 
While it may be a trite and overused term, 'thinking outside the 
box' is the best description of what should happen here. 

Winnow the list of possible solutions objectively 

That s not to say that standard solutions should he tossed 
aside either. All solutions, both conventional and unconventional 
need to be looked at with the same objectivity, Don't worry that 
you will have such a large list of solutions that you won’t lie able 
to pick a solution, There are always going to be requirements 
that will help determine the solution. For example, while a fibre 
- channel SAN may be a faster way to serve files, if you don’t 
have a fibre-channel setup in place, the fiscal and time costs of 
such a solittion may remove it from the list, 

Space limitations are an example of a factor that is going to 
apply to any solution, and is platform neutral. If you only have 
a small amount of space in your server room for a new server, 
then a solution that involves hundred - station Linux clusters 
may not be practical at this time. Network limitations are another 
example. That reconditioned AS/400 may indeed be a cheap and 
fast server, but if it can only use Twinax and you only can 
implement Ethernet, then this Is not a good solution. 

The point is, make sure that you use unavoidable limitations 
to winnow your solutions list first. Network, physical, fiscal, 
these are all limits that should take precedence over the 
operating system and platform for the server. 

Standards are good, but in moderation 

So now you have a manageable solutions list. What about 
computing standards? Well, as long as you don't go overboard, 
and apply standards to where they need to be applied, they can 
be an aid. Too many companies standardize on operating system 
or application, when they would be better off standardizing on 
data format. If you want to ensure uniformity of final output, 
standardizing on Windows and Word or Solaris and Lai ex will not 
do nearly as much good as standardizing your fonts, image 
formats, and data formats. Limiting your font usage, standardizing 
on a small number of image formats, such as TIFF, JPEG, MPEG, 
EPS, etc,, and using Acrobat as your final output of choice Is going 
to give you all the benefits of standardization, but will leave you 
with a far more capable tool box than a single platform and 
application will. It also means that if the preferred application or 
platform is under attack, you can still get work done. 

This does not mean just randomly seed different platforms 
about your network. First, if you have 100 people in a group 
using Windows, and one person using a Mac, all you create are 
problems for yourself. Implementing a different platform has to 
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be done in a planned logical way. Willy - nilly is a fun way to 
do many tilings, but network design Is not one of them. 

Common knowledge is always wrong 

One of the signs that a solution is going to be bad is when 
it stans with any variant of “Well everyone knows,,” There is 
nothing in computing that everyone knows that is ever 
universally correct. “Everyone knows" that AppleTalk is chatty 
and getting rid of it will make things better. Well, to quote an 
Apple engineer on the AppleSharelP team: 

“On Bandwidth: 

An idle connection to an AppleShare server (via IP) sends 2 tickle packets of about 64 
bytes in size every 30 seconds (call it 4 bytes/second or 0,00024% of a 10 Mega Bit 110 
[hse-T] connection <1 may he off by a factor of 10 either way. its early>) When transferring 
files, AFP is just as efficient as any other well implemented IP protocol, a single client can, 
under ideal conditions fill the pipe with minimal overhead. Fora 16k read/write we have 
28 hues of AFP/DS1 protocol info on top of 780 bytes of TCP/IP protocol info fora payload 
efficiency of aboui9l% (it takes 12 packets to move l(>k of data) 

So maybe everybody knows nothing. Hie point here is 
don l assume anyiliing. The solution is good or bad based on the 
facts, not assumptions, attitudes, personal prejudices, the 
magnetic pull of the Mcxm, Kentucky windage, etc. If you let 
anything but the facts and reality guide your selection of a 
solution, then you may as well throw darts at the list, you'll have 
as much luck that way as any, and it's probably more fun. 

Implementing Diversity 

So. the solution to the new file server is a new server. It lias 
to be able to authenticate against your active directory servers 
transparently, it has to support Windows clients smoothly, and it 
has to fit into your Veritas backup solution. Congratulations, you 
have a multitude of platforms to pick from. Samba can easily 
handle Windows clients and use an upstream Active Directory 
server to handle authentication requests. Veritas supports a wide 
range of client platforms, including Mac OS X, so you can freely 
pick from any of them. 

You'll get a new, faster file server. Your users will be 
happier because they get to their files faster, with the same 
reliability. Because you can choose from a wider range of 
vendors, you get better competition for your business, which 
means your upfront costs are smaller. But even better, what 
happens when a Windows virus comes ripping through your 
network and hits that Linux file server? 

It dies. Slops. That machine isn't infected. Those files are 
safe. What happens when some cracker larvae is using the latest 
Solaris hack to get past your firewall, and hits your Mac OS X 
file server? The same thing. He now has to figure out what this 
operating system is, and then find ways to crack it. He may 
indeed find a new crack, but that Solaris - specific hole that he 
used is closed at least here. 

By having a genetically diverse network, you aren't losing 
anything, except the loss of security and capability that comes 
with a building full of genetically identical clones. Your up front 
costs don't have to be any higher. You may have a learning 
curve on the new platform, but those aren't as bad as they seem 


to be, and the Internet has terabytes of information that will help 
you along. By having a mixture of server platforms and client 
platforms you create firebreaks on your network. You ensure 
that no single attack that is targeted at a single vulnerability Is 
able to completely compromise your entire network unchecked. 
While Code Red may load down an iPlanet web server, it a s 
certainly not going to abuse it in the same way as it will an 
unpatched IIS server Outlook viruses become merely amusing if 
you aren’t using Outlook as your only email client. 

In addition, you gain a whole host of capabilities that you 
simply cannot achieve in a homogenous environment. Unix, 
Windows, Mac OS X, A5/40GS, NetWare, ‘BSD, Linux, el al all 
have unique strengths and weaknesses that can compliment 
each other. There are products that only exist on a single, or 
small number of platforms that can lie of great use to you, but 
only if you have that platform available. 

Even better, when you combine a genetically diverse 
network with a well - thought out set of prophylactic measures, 
such as antivirus programs and intrusion monitors, both methods 
become more effective and secure. Even if one of your low - 
infection platforms does get infected, the damage that occurs 
will be limited because the other platforms won't be infected 
Not only Ls the damage mitigated, but you also have more time 
to prevent a similar problem on the other platforms. The 
prophylactic protections don't take up as much of your time, 
because they have a genetic backup in place. They have less to 
watch out for, because your firebreaks are intercepting and 
halting much of the damage before it hits vulnerable systems. As 
well, other prophylactic measures can help you stop the 
problem before it hits vulnerable or targeted systems. 

Genetic diversity is just another, less common way of 
removing a single point of failure. If you aren't going to do that, 
then why bother with RAID and failover servers, etc? 

Conclusion 

Genetic diversity isn't just some fad, or some keen idea that 
has no basis in reality, In fact, it has mil lennia of proof that it is 
a good tactic. It is a proven way to keep any population healthy 
and functional, no matter if you are talking about potatoes, 
humans, trees, cows, military Forces, or computers, li may Lake 
more work than a clone farm, but the benefits are real, tangible, 
and undeniable. It's not a panacea, but it can, and will make 
your network stronger and more capable. 

In the end, there is no magic bullet. Every form of 
protection, including genetic diversity on your network has a 
weakness. You have to combine network genetics and 
prophylactic measures, along with a Iol of planning, to achieve 
the best results. Use both. The next time you buy a new box, if 
you already have a lot of lhai platform, see if maybe you can get 
the same, or even better results from a different platform. You 11 
learn more, you 11 gain more capabilities, and the next time the 
Legion Of Bad People unleashes some hideous Windows, or 
Linux virus, you'll have a much better time than your 
counterparts in the lands of Windows and Linux clones. 
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Introducing 360 One VR 



Developed by EyeSee360 and Kaidan, 360 One VR™ is an 
amazing product that captures a complete 360° panoramic image 
in a single camera shot. Years of extensive research have pro¬ 
duced an innovative solution that creates an immersive image 
without the restrictions or compromises normally associated 
with panoramic photography 

360 One VR consists of a lightweight and rugged proprietary 
optical device and the innovative EyeSee360 Photo Warp™ soft¬ 
ware. The unique mirrored optic provides a complete 360° hori¬ 
zontal panorama with an outstanding 100° vertical field-of-view 
(50° above and 50° below the horizon). 

This vertical field-of-view is substantially greater than competi¬ 
tive offerings and brings single-shot panoramic technology into 
the mainstream. With 360 One VR, single-shot panoramas can be 
used for interior shots and other situations where it is important 
to look up and down as well as side-to-side. 

When coupled with a 3 megapixel or greater digital camera, the 
360 One VR, with its precision coated glass optics, provides a 
level of quality that rivals conventional "stitched" solutions 
requiring two or more images. Since 360 One VR requires only a 
single shot to capture the full 360° view, action scenes with mov¬ 
ing objects are easily photographed. 

360 One VR can capture detailed panoramic images in crowd 
scenes, at concerts, on city streets, at sporting events, and even 
from moving vehicles. Photographers avoid the stitching or 
seaming required by competitive multiple-shot systems, thereby 
eliminating the possibility of visible seams or exposure differ¬ 
ences across the panorama. 

The EyeSee36Q PhotoWarp™ software quickly and easily 
processes a 360 One VR photograph into a viewable panoramic 
image. The straightforward, simple-to-use interface automatical¬ 
ly generates QuickTime VR© panoramas, thumbnail images and 
web pages. PhotoWarp can also produce unwarped images suit¬ 
able for Java™-based panoramic viewers and printed output. 

Visit our website, http://www.360OneVR.com for more info. 
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By Dan Wood, Alameda CA 


The Beauty of Categories 


Use This Objective-C Feature to Make 
Your Cocoa Code Cleaner 

Ask any experienced Cocoa programmer what they like the 
most about Objective-C and the answer will invariably be 
“categories." Categories is one of the features of Objective-C, 
not found in Java or 0+*, that raises the bcxly temperature of 
developers if you suggest they use another language. 

Whm is It, and Why Use It? 

A category is an extension of an existing class. But unlike 
inheritance, in which you create a new class that descends from 
another class, a category is like a remora, attaching itself to the 
belly of a shark and getting a free ride. By creating a category, 
you add new methods to an existing class, without needing to 
create a new one. 

Writing in a language without categories, die programmer is 
often faced with the need to perform minor operations, acting 
upon an object for which source code is unavailable These 
routines might end up as methods in Lite application class that 
needs to perform those operations, although thaL doesn’t 
promote reusability, since die operations are tied in with the 
enclosing class. A better approach, one more commonly used, 
is to collect these operations into a utility class. 

On an open-source web application framework that 1 
worked on, called Janx (available at www.bearriver.c 0 m) there 
is a siring utilities class, for example. This class has operations 
to parse strings representing dollars and cents, encode a string 
for HTML display, generate a hexadecimal representation, build 
an MD5 digest from a string, and so forth. Each of these 
methods takes a string to operate upon as one of its parameters. 

This ‘utility class" approach isn't particularly elegant either. 
Dissimilar operations tend to be grouped together into the same 
class. Each method must be passed in the object to operated 
upon as a parameter, which means that the functions that you 
write look and operate differently from methods that arc part of 
the class, even if they perform similar operations. 

Another approach to extending functionality is to create a 
subclass of an existing framework object, and add your new 


functionality into the subclass. For instance, you might subclass 
an existing “image” class to add operations. The problem is that 
you must now be sure to work only with instances of your new 
class; any objects that aren’t must be converted, 

If you are programming in a language such as C++ or Java 
without categories, though, you just deal with these limitations; 
they may not seem like limitations at all 

When you write an application in Cocoa using Objective C, 
you have the ability to put such functions directly into an existing 
class by creating a category on that class. No, you don't 
recompile the class with new methods in the file; in fact you 
usually don't have the source code to the class you are adding to. 

Utilities vs. Categories 

Let’s take a look at how this might be done by implementing 
a utility function to strip quote marks off of a string. (We ll 
implement them both in Objective-C just to keep the playing 
field level.) We implement il as a method in a string utility class 
in listing 1 and 2; we implement it as a category on NSString in 
listing 3 and 4. 


Listing 1: String!Jtilities.h 

#import <FDundation/Foundati(5n.h> 

^interface StringUtilities 

+ {NSString. stripQuotes: [NSString NinString; 
&end 


listing 2: StringUtiiities.ni 

//itnport ’’StringUti lities. h" 

^implementation StringLftilities 

+ (NSString B ) stripQuotes 1 (NSString *]inString 
I 

NSString * result = inString; // Raum iiritring if no stripping needed 
irat leu - [inStrlng length!; 
if (ien )= 2 

&& *** = [inString characterAtIndex:G] 
firfie tJM = [inString chsracterAtIndex:len-l]) 

1 

// Get the substring that doesn’t Include first and last character 

result = 

[inString substringWlthRangejNSMakeRangeCl ,len-2)l; 


Dan Wood wrote Watson for Mac OS X, a Cocoa application that connects to a variety of Web services. You can reach him at dwood@karElia.com. 
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return result; 
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Listing 3: NSString+misc.h 

//import <Foundation/Foundation,h> 

©Interface NSString ( misc ) 

- (NSString *) stripQuotes: 

©end 

listing 4; NSString-hnisc.tn 

//import "NSString+nilsc.h M 
©implementation NSString ( misc ) 

- (NSString *) stripQuotes 

( 

NS S t ring * resu lt = self: // Return self if no stripping needed 

int len =■ (self length] ; 
if (len >~ 2 

&& = [self characterAtIndex:0] 

&& f,ff — [self cTiaracterAtIndex:len-l] 1 
I 

// Get tile substring that doesn't include first and last character 

result = [self substringWithRange:NSHakeRangef1,Ien-2) 1 : 

return result; 

I 


The implementations of these category looks much like the 
utility class; the main difference is that the string to operate upon 
is not passed in as a parameter; it is accessed with the self 
keyword. Things start to kxjk different when you compare code 
that uses the category instead of a utility class. Here are snippets 
that use each approach. 


Snippet using a utility class 

NSString ‘stripped = 

[StritigUti titles stripQuotes:theValuel; 
[lineDict setQbjectstripped 

forKey: [theKey uppercaseString]]; 

Snippet using a category 

NSString ‘stripped = 

[theValue stripQuotes]; 

[lineDict setQbject:stripped 

forKey:[theKey uppercaseString]] ; 


The code using the category is quite a hit cleaner because 
we don't have to he conscious of a separate utility class; it is just 
another operation on the string, just like the built-in 
uppercaseString method on die last line. 


Writlng Categories 

A category must have an ©interface and ©implementation 
section, just as a class. After the name of the class being added 
to is an arbitrary name which describes what the category is for. 
in parentheses. The example above uses "misc 11 as its name. 
Normally, a category on a class gets its own “,h" and “.m" 
file; a convention is to name the file based on the class name 
concatenated with , ‘+" to the category name. For example, the 
file NSImage+bitmapan would be expected to hold 
©implementation NSImage ( bitmap X This is not strictly 
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necessary; however; you could make a quick category interface 
and implementation right in your class file that makes use of the 
category; Lhis would only be practical if it was not needed 
outside of the associated class. 

Methods are declared and implemented just as they would 
be for any standard Gbjective-Cs methods. Keep in mind, 
however dial self is the class that you are implementing; feel free 
to send messages to self to operate on that object. 

The one big limitation on categories is that you can only 
add functionality; you cannot add new data members to die 
class. There are no curly braces in the @ interface section of a 
category, if you feel the need to add data members, you may 
want to consider subclassing instead. 

Using Categories 

The best thing about categories is that you can add 
whatever features to Cocoa you'd like to that you feel are 
“missing/' Frustrated that NSImage lacks the +[N5Image 
iniageFratnData:] method? Add it in yourself! You can write 
generic categories and use them on all your projects, and make 
use of them as if you were using functionality of the classes 
provided by Apple, On you can create categories on an object 
as needed, whenever it seems more intuitive to extend the 
functionality of a Cocoa class rather than write a function to act 
upon that object. 

You can even use categories on your own code, to help 
factor your application’s classes into smaller, more manageable 
chunks. For instance, you might create separate categories to 
partition your document controller into preferences 
management, window management, and general functionality. 
Doing so makes your Files smaller and makes your project more 
navigable. Cocoa itself makes heavy use of categories in this 
manner; it allows classes to be created in one library 7 (such as 
Foundation Kit) and then extended in another (such as 
Application Kit). 

One of the best places to use a category 7 is to split up your 
class's private methods from its public ones, to overcome a 
limitation in Objeetive-C. Unlike C++ and Java, there’s no way to 
specify the access of a method using keywords. So the solution 
is to create a new ©interface for your category at the top of your 
class's +m" File, holding the methods you do not want to lie 
exposed in the file. This category would have a name such 
as "private’ 1 to indicate its purpose. Below that, the 
©implementation section of your class can then hold the 
implementation of both the public methods ( declared in the \ff 
file) and the private methods (declared in your private category). 
Other classes will not be able to see your private methods. 

Usually, you will find yourself adding categories to classes 
in the Foundation Kit, because this kit tends to hold containers 
and utilities. You can even add categories to NSObject so that 
any object can respond to your new functionality. When there 
is a technique that requires bridging into Carbon or Core 
Foundation to accomplish your task, you could wrap it into a 


category on a related class (or even find one online that 
somebody else has already written), so that if such functionality 
were to make its way into a future version of Cocoa, your code 
wouldn’t have to change much. 

Examples 

Where you make use of categories is limited only by your 
imagination. It is useful to look at other people's source code 
just to get a sense of what kinds of categories are possible. 
Many source code packages are available for downloading at 
softrak.stepwise.com. 

Here are a few examples that I have used in my own code. 
To make use of these, you would need to create ©interface and 
©implementation sections following the guidelines above. 

Category for NSImage 

A method to set an image size to be the size of its associated 
NSBitmapImageRepresentation so that the image displays at full 
size of 72 DPL It finds the first bitmap it can, and sets the size 
of the bitmap and of the image to the pixel width and height, 

(tiSJma^e *) nonnalizeSize 
I 

NSBitmapImageRep *t.heBi tmap = nil; 

MSArray *reps 77 [self representations]: 

NSSize neySize: 

int i; 

for (i ^ 0 : i < [reps count! ; i++ ) 

t 

NSImageRep *theRep - [reps objectAtludexii]: 

if (ftbeRep isKindOfClasst [HSBitmapIni&geRep class]]) 

I 

theRitmap = (NSBitmapImageRep UFheRep: 
break: 

I 

i 

If (nil t— theBitmapj // Found a bitmap iq resize 

I 

newSize.width = [theBitroap pixelstfide]: 
newSize.height - |theBitmap piste IsHigh] : 

[theBitmap setSis«;newSIze| : // resize bitmap 

[self setSize;newSize] ; //resize image 

i 

return self: 


Category 7 for NSBundle, NSDictionary, NSString, etc, 

A comparison method (passing in another object of the 
same) so that you can sort an array of those objects by some 
property, using -{NSMutableArray sortUsktgSelector:], For 
example, you could son an array of dictionaries l>y the value of 
their “name" key by passing in the selector for the following 
method. 

(NSComparisonResuIt) compareSymholName: 

(NSDictionary M inflict 
t 

MSString ‘tuyName = [self objectForKey-©"name"] : 

NSString *otherName - [inflict objectForKey:@°narae rt ]; 

return [myNatac caselnsensitiveCasnpare;olherMame] ; 

I 
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VXA FireWire 


"/ can stick 
my entire 
hard drive 
onto a tape 
7 times 
—that's Just 
plain cool!’* 



The High-Performance 
Tape Storage Solution 
For Apple Users 


Other backup media, such as CD-RWs and DVD-RAMs, 
si mply can T t compare to VXA-1 tape technology when it 
comes to capacity, transfer rate and overall price. 



Fast, economical and easy-to-use, 
VXA FireWire offers: 

Ultimate File Security 

* 100% Data Restore and Interchange 

* Plug-and-Play Connectivity 

Sharable Media 

* Multi-Gigabyte File Transport 

* Portable, Hot-Pluggable 


Technology 

- 

vxATa P e 

IrnationTraran 

DVD RAM 
CD RW 
Zip 


Capacity 

In MBs 


33000 

10000 

9400 

700 

ISO 


Transfer Rate Price 

in MB/sec per MB 


3 

$0.03 

1 

$0.05 

17 

$0,05 

1.9 

$0,50 

1.2 

$0,76 


Real Time Digital Video 

Cross-Platform Compatibility 
* FireWire/IEEEI394/iLink Supported By 
All Major Manufacturers 


Call Exabyte sales at I-800-774-7172 
or visit us on the web at www.exabyte.com 

Tape Storage By 

-VXA- 2Exabyte’ 


© Copyright 2002 Exabyte Corporation . All rights reserved, VXA and VXAtape are registered trademarks of Exabyte Corporation. 








(NSString *) temporaryDirectory 


Category for NSStrlng 

A method to return an attributed string as a blue underlined 
hyperlink, so that text fields can respond to link clicks as in a 
web browser. Text in an NSTextView with these attributes will 
send the message of textView: dickedOnlink: atlndex: to the 
view's delegate, 

(NSAttributedString *) hyperlink 

( 

NSDictionary *attributes= 

[NSDictionary dictioneryWithObjectsAndKeys: 

[NSNuntber numbsrWithint:NSSingleUnderlineStyle] , 
NSUnderlineStyleAttributeName, 
self, NSLinkAttributeName. // link to the string itself 

[NSFont systemFcmtOfSize:[NSFont smallSystemFontSize]]. 
NSFontAttributeNarae, 

(NSColor blueColorJ, NSForegroundCalorAttributeName, 
nil]; 

NSAttrib.ut&dString *result^ 

[[[NSAttributedString alloc] 
initWithString:self 
attributes:attributes] autorelease]: 
return result: 


Category for NSWorkspace 

A method to return the path of the current user's temporary 
directory. This makes use of the Carbon FindFolderO API, and 
then converts the C string into an NSString. 


Impact your bottom line while working with 
dedicated proponents of Apple technologies 



With us, your only constant is success. Our custom solutions help our 
clients excel their business objectives and effectively target their 
audience. That’s why we suggest that we run your technology while 
you play the winning shot 


Core Competencies 

WebObjects development 

Mac OS X application development 

Cocoa application porting 

Carbon porting 

Mac OS product maintenance 

Windows/Mac OS/Unix porting 

Cross-platform development 


Service Offerings 

Offshore Project Development 
On-Site Staff Augmentation 
Off-Site Project Development 
User Training 


For More Information 

visit http;//www,avestacs.com 
Email: mithu@avestacs.com 


A vesta Computer Services, Ltd. 
USA , EU . Asia 


( 

char s [1024]: 

FSSpec spec; 

FSRef ref; 

short vRefNum: 

long dirlD; 

If ( FindFolder( 

kOnAppropriateDisk, kChewableltemsFolderType, true, 
&vRefNunt f &dirID ) = noErr ) 

f 

FSMakeFSSpec[ vRefNum, dirID. ,MI . kspec ): 
if { FSpMakeFSRef(&spec r &ref) = noErr ] 

I 

FSRefMakePathUref t s, sizeof(s}): 
return [NSStrlng strlngWithCString;sj : 


return nil: 
I 


Category for NSSet, NSArray, etc, 

A method to build a string listing the strings in a collection, 
separated by commas. It enumerates through all objects in the 
structure, adding each string and then adding a comma. It then 
removes the extra comma (and space) at the end, after the list is 
traversed. 


(NSString show 

1 

NS String 

collection 

NSMutableString 

NSEmimerator 

NSString 


* result — @ ,r 11 ; // empty string if none in 

*baffer - [NSMutableString string]; 
•theEnum = [seif objectEnumerator]: 

* theldentifier: 


while [till 1- (tieIdentifier [theEnum nex Object]) ) 

( 

[buffer appendString;theIdentifier]; 

[buffer appendstring:®"• "J : 

// Delete final comma*space from the siring 

if (![buffer isE quel To St ringj@""]) 

[ 

[buffer deleceCharacLetslnRange:NSHakeRange( 

[buffer length I 2, 2)] \ 
result = [NSString rttingWithString;buffer]: 
l 

return result; 


Conclusion 

Hopefully you have been convinced that categories are a 
useful construct for programming in Cocoa, If you're not using 
Objective-C, you can certainly function without them, But if you 
are, then categories arc a great way to make your code more 
readable, more reuseable, more maintainable, and simpler. 
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PROG RAM IV 
CHALLENGE 


S 



by Boh Boonstm, Westfoni MA 


MaTCHSTICKS 

Some time ago, Robin Landsbert sent me a suggestion for a 
Challenge based on a game he called Nim. In Robin's version of the 
game, matchstidcs were arranged in rows forming a triangle, one 
matchstick in the top row, two in the next, three in the next, etc. 
Two players take turns removing one or more match,sticks from any 
single row of the board. The object is to make your opponent take 
tlic last matchstick. 

A little research suggests that this version of the game might not 
be very difficult. So, in the tradition of the Challenge, we will add a 
few twists that might make die game (and the Challenge) more 
interesting. First, we will arrange our matdisticks in a square grid 
instead of a triangular one, and allow players to remove matdisticks 
from either a single row or a single column on a given turn* Second, 
w r e will not put a matchstick in every position in the grid, leaving a 
small number of positions empty, perhaps on the order of 10%. 
Third, we will restrict a player’s moves to removing matdisticks with 
no intervening holes. That k a player can remove die n+1 
matdisticks in row r located in columns c through c+n only if a 
matchstick is present in each of those locations. And finally, we w ill 
play two versions of the game, one where the player taking die last 
matchstick loses the game, and one where die player taking the last 
one wins the game. 

The prototype for the code you should write is: 

void ItiitMatchsticks( 
short dimension, 

/* game is pl:twd on :i square bam! of size dimension x dimension 7 

const char *board, 

t lxiard|n>w 4 diimmikm +- col] IS hKird cd! (row,col) 7 
t board []=1 represents a msitchsikk, represents an empty cell */ 
bool playEirst, 

t true if you wilt pluy first in this game 7 
bool lastMatnhstickLoses, 

r true if taking the hint matchstidc loses die game, 
false if taking the last one wins the game 7 
short opponent 

r identifier for your opponent in this game 7 


Vo1d Oppone ntMo ve( 
bool playingRow, 

r true if opponent played along a row, fitlse if a tong a column 7 
short rowOrCoiuinnNumber. 

r number of the (origin zero) row ( pla>ingRow r =mie) or 
column (playingRow—false) 
iliat die oppoomt played 7 
short startingColOrRow, 
short endingColOrRow, 

r if pteyingRtiw—true, die opponent played from 

(tow,ct>r>==( ro wOrCohurmM Limlx:r,siarUiig( olOrltow) 
to (iow.cofi^rowfhCo lumnN timber, cndiiigCoJOrilowO 
if playingRuw—£Tse, the opponent played from 

(raw t col)=(stirtingC olO rRo w,m wOrCol umn N umber) 
to (rovv l cd)==(entlkigColCMow 1 row , OrColiiiunNtmibcr) 

7 

const char *board 

t board after your opponent's move 7 


const char *YourMove( 
bool ' f playingRow. 

t true if you played along a row, false if along a column 7 


short * rowOrColimmNmiiher, 

p number of the (origin zero) row (playingRow=true) or 
column (pkyicgRow=faIse) 
tint you played 7 
short *startingGolOrRow, 
short *endingColOrRow 

P if *playmgRow^=true p you played from 

(mw.et j!)==C n >w OrColumnN timber, *siaitir»gl ioJDrRow) 
t o ((x)w h cqI)=^rowOrODliimiiN umber, VndingColOrRow) 
if + playingRow—false, yon played from 

(r< > w, co Ij^fstaitin gGiJOrRc)w, *m wQrO >h min Number) 
to(rnw,cof>^enditigQ)KMow,7tJwOiO>lumnNumber) 

7 

r return value is a pointer to a board after your move 7 

): 

The objective of the Challenge is to win as many games as 
possible against your fellow contestants, while expending as little 
execution time as possible. Each game begins with a call to your 
InitMatchsticks routine, where you are given the dimension of the 
game, the initial board configuration, the identity of your opponent, 
whether or not you play First, and whether the objective is to take or 
not take the last matchstick (lastMatchstickLoses). When it is your 
turn to move, your YourMove routine describes the move you are 
making (playingRow, rowOrColumnNumber, starringColOrRow, 
endingColOrRow) and returns a pointer to your view of what the 
lxiard looks like after your move. When your opponent moves, your 
OpponentMove routine is provided with a description of the 
opponent’s move, and the board configuration after that move. 

The Challenge wall be scored as a round robin tournament, 
or another fair scheduling mechanism. Each player will play first 
and play second against each scheduled opponent an equal 
number of times for each lest case. Each player wall play to w in 
by taking the Iasi matchstick, and play to win by making the 
opponent take the last matchstick, an equal number of times 
against each scheduled opponent for each test case, A player’s 
score will be dimensionA2 points for each win, minus a penalty’ 
of 10 points per millisecond of execution time. You can earn a 
bonus of up to 25% of your score based on a subjective 
evaluation of the clarity of your code and commentary. 

This will be a native PowerPC Carbon Challenge, using the 
Metrowerks CodeWarrior Pro 7.0 development environment. 
Please be certain that your code is carbonized, as I may evaluate 
this Challenge using Mac OS X. Unfortunately, this Challenge 
cannot accommodate alternative development environments, 
because pairs of solutions need to compete against one another 
in a single executable. 

Winner of the March, 2002 Challenge 

The March Challenge required contestants to solve the 
Mega minx, a twelve-sided puzzle in the shape of a dodecahedron. 
Each of the twelve faces of the Megaminx can lie rotated clockwise 
or counter-clockwise, with five consecutive rotations of a face in the 
same direction bringing the face back to its original position. Each 
face is divided into eleven facelets, five corner facelets that each 
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border three faces, five edge facelets that each border two faces, and 
one center face let. The faces are colored with six colors, opposite 
faces sharing the same color. Hie input for the Challenge was a 
sequence of files that each described a scrambled Megaminx, and 
the required output was a sequence of rotations that solved the 
puzzle. Scoring was based on the execution time required to solve 
the scrambled puzzles. Contestants earned up to a 25% reduction in 
their time if they also displayed the puzzle solution. 

Two contestants, Ernst Munter and Allen Stenger, submitted 
solutions for tills Challenge. Both contestants acknowledge the 
information provided at two Megaminx web sites, one provided by 
Mefferfs Puzzles at http://www.meffertspuzzies.com/puzzles/megasoil.htmt 
and another by W, D Joyner. Ernst used the approach described in 
http://web, usna.navy.mil/~wdj/megam.htm, one that solved the problem 
quickly, but generated solutions with a large number of moves. 
Ernst first moved the comer pieces to the proper positions, then 
moved the edge pieces to the proper positions, then oriented the 
comers, then oriented the edges. Allen t<K>k the nine-step approach 
described at the Meffen site, augmented with a modification from 
http^/web.usna,navy.mil/~wdj7megaminx.htm, an approach that generated 
shorter move sequences, but took more execution time. 

Both contestants provided display options in their entries, 
Ernst's program has a compile-time option to generate a two- 
dimensional depiction of the Megaminx as the solution is 
generated. He included an option to display macro moves in a 
single step, which made it easier to see what was going on. 
Allen’s entry has a separate program, written in Cocoa and using 
OpenGL to display a three-dimensional Megaminx. Allen 
included options to read in a puzzle description file and a 
sequence of moves, controls to rotate the viewpoint, and controls 
to rotate a slice of the puzzle. 

By the stated rules of tills contest, the solution requiring the 
least amount of execution time, after considering the display 
bonus, is the winner. Congratulations to Ernst Munter (Kanata, 
ON, Canada) for winning the Megaminx Challenge. I am taking 
the somewhat unusual step, however, of providing both solutions 
in the online archive, and printing the better-commented solution 
by Allen Stenger in this article. 

The table below lists, for each of the solutions submitted, the 
total execution time in microseconds, the time reduction awarded 
for providing a display option, the net penalty' points after 
subtracting the bonus from the execution time, and the 
cumulative number of moves required to solve the ten test cases 
used to evaluate solutions. It also lists the programming language 
of each entry. As usual, the number in parentheses after the 
entrant’s name is the total number of Challenge points earned in 
all Challenges prior to this one. 


Name 

Exec. Time 

(microsecs) 

Display 

Bonus 

Penalty' 

Points 

Moves 

Language 

Ernst Munter (275) 

37331 

25% 

27998 

15030 

o+ 

Allen Stenger t39) 

347335 

25% 

260501 

6440 

OVObjC 


Top Contestants ... 

Listed here are the Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants. 


Rafik 

Name 

Points 

Wins 

Total 



(24 mo) 

(24 mo) 

Points 

l 

Munter, Ernst 

275 

10 

862 

l 

Sa*ian, Tom 

52 

l 

210 

3. 

Stenger, Allen 

-r) 

t 

114 

4. 

Rieken, Willeke 

it. 

1 

134 

5. 

Wihlborg, Claes 

40 

2 

49 

6. 

Taylor, Jonathan 

57 

1 

63 

9. 

Gregg, Xan 

20 

1 

140 

10. 

Mallctt, Jeff 

20 

1 

114 

11. 

Cooper. Tony 

20 

1 

20 


... and the Top Contestants Looking for a Recent Win 

In order to give some recognition to other participants in die 
Challenge, we a 1st) list the high scores for contestants who have 
accumulated points without taking first place in a Challenge during 
the past two years, listed here are all of those contestants who 
have accumulated 6 or more points during the past two years. 


Rank 

Name 

Points 

Total 



(24 mo) 

Points 

7. 

Sadeisky, Gregors' 

22 

24 

8 

Boring, Randy 

21 

144 

ti 

Schotsman. Jan 

16 

16 

11 

Shearer. Rob 

15 

62 

15, 

Han, Atan 

14 

39 

16. 

Nepsund. Ronald 

10 

57 

17. 

Day, Mark 

10 

30 

18, 

Desch. Noah 

10 

to 

19. 

Flowers, Sue 

10 

10 

20. 

Maurer, iktaiian 

7 

108 

21, 

teltner. Will 

7 

7 

21 

MilEer. Mike 

7 

7 


There are three ways to earn points; (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are; 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5 tli place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 
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Here is Allen s Megaminx solution: 


CSolver.cpp 

mMmimmmmfMfmimmimtmfMi 

// 

// Megaminx (MacTech Programmer's Challenge, March 2002) 

// Written by Allen Steiger, March 2002 

// 

// Conceptually we mute colors rather than feces; this simplifies the problem of 
// determining the orientation of each edge and corner piece. 

// 

//We follow the solution given by Meffert's Puzzles and Novelties; 

// see http://ww w.meffcrtSrpuzides.ajm/pLtZides/megasoJl .himl 

// 

//Terminology: corner piece is at a vertex of the Megaminx and has three feedets, 

// edge piece is at an edge between two faces and has two faedets.The smaller 
// pentagons in the center of each face never move away from the face and so we 
// ignore them. 

// 

//A vertex can he specified by its vertex number,however edges don't have numbers 
// and are usually specified by the two feces they lie on.There is a variety of constant 
// tables for walking through the feces. 

// 

// COLOR AMBIGUITY 

// 

// Because the same eolors are used for two faces, it appears that there might be Some 
// ambiguity in the pieces; dial is, radially-opposite comers have the same colors, and 
// and radially-opposite edges have the same colors,so how do we know whether to 
// place a comer or edge in the Northern or Southern part of die Megaminx? 

// 

// ‘The comers are actually not ambiguous because the orientations 
// are different; so for example there are two corners with 
// colors 1,23, but the one on the North Pole has the eolors 
// 1,23 in clockwise order and the one on the South Pole has 
// 1,2,3 in counterclockwise order.Therefore we can always 
// tell from die comer which part of the Megaminx it goes in. 

// * The edges really are ambiguous. It Is not necessary to pul 
// each edge back in its original place, bttt in some situations 
// we would get to Step H and be unable to orient the South 
// Pole edges because of an earlier placement we made. To solve 
// the Megaminx we must follow some parity rules; see 
// 

// Coreyannc Rick wait, "The Fundamental Theorem of lire 
// Megaminx", http://web. usna, na w. mil/ - wdj/megaminx.htm. 

it 

// We will detect Lite problem case in Step 6 and take evasive action. 

tt 

//A simple example of the problem is a Megaminx that is solved except 
// for die two edges: 

// 8,73 

// 9,7,2 

//This one cannot he solved by the published Muffed method because 
// Site South Pole edges arc not correctly placed in Step H. 

// 

iiitiiiliifiiiiitiiifiiiiiiifitjiififtiitiHiiiiiitiUiiliiifiiifiiiii 

//include "CSolver 
//include " CMe garni nx t h" 

//include "CMegaroinxApp. h n 

//include <cassert> 

//include <sstream> 


// stime fixed faces we use 

const int kSouthFoleFace = 7: 

iititltiiiliiiiiiiiitiiiiifiiififijiiiiiiittfiiiijtUWWtfiiiMift 

CSelver: :CSolver(CMegmninxS rMega) : 

FMega (rMega) 

{ 

I 

CSalver::~CSolver (} 

( 

I 


void CSolver::Solve() 

l 

!t call all the solution steps 


Step3(): 

Step4(}; 

Step5(}: 

Step6(J: 

Step? (); 

Steps () : 

Stepsn : 

Step 1 DO : 

Step!1(); 

I 

void CSolve r:; DoLUU (CMeganii nx: l face_t leftFaee. 
CMegaminx::face_r rightFace) 

I 

fMega .WriteComment("DoLUlT); 

fMega,Slice(leftFaee, CMegaminx::eCounterCW* 1); 
fMega.SlicefrightFace. CMegatninx:: eCW, 1): 
fMega*Slice(leftFaee, CMegaminx::eCW. 1): 
fMega*51ice(rightFace. CMegaminx:leCounterCW* 1); 

1 

void CSolver: :DqRUU(CM egaminx:: fs'ce„t leftFaee. 
CMegaminx:;face_t rightFace) 

( 

fMega. Wri teComment ("DoRUU"); 
fMega,Slice(rightFace t CMegaminx;:eCW, 1): 
fMega.Slice(leftFaee. CMegaminx::eCounterCW* 1): 
FMega * Slice(rightFace, CMegaminx::eCounterCW. 1); 
fMega,SlicedeftFace, CMegaminxeCW, lj ; 

} 

void CSoiver: iDqRLL(CM egaminx: :face_t leftFaee, 
CMegaminx::face_t rightFace) 

I 

fMega, Write Comment (" DoRLL"); 

fMega.Slice!rightFace. CMegaminx::eCounterCW* 1); 
fMega.Slice(leftFaee, CMegaminx::eCW, 1); 
fMega.Slice(rightFace, CMegaminx::eCW, 1); 
fMega.Slice(leftFaee. CMegaminx::eCounterCW, 1); 

) 
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void CSolver::BoLLL (CMegaminx::face_t leftFace, 
CMegaminx;:face_t rightFace) 

[ 

fMega, WriteCominentf^DoLLL") ; 

fMega*Slice(leftFace* CMegaminx::e€W, 1); 

fHega * Slice (rightFace* CMegaminx: :eCourLterCW* 1) ; 

fMega.Slice(leftFace, CMegaminx:: eCounterCW. Dr 

fMega.Siice(rightFace* CMegaminx::eCW, l): 


void CSolver::¥isitAllGorners[CCornerVisitor SaVisitor) 

i 

for (int i - 0; i < CMegaminx;:kNumVertices; i++] 
aVisitor*VisltCorner(i): 

) 

bool GSolver;:CheckEdgeParity(} 

t 

// this holds the permutation of the South edges;. It is 
// hi two ^-edge pieces: 

// (H: South Equator edges, indexed same as SouthEqEdge arrays 
// 5-9: South Pole edges, indexed same as Sou [Pole Edge arrays + 5 
//The entries are also these indices; pemi[i| contains the edge 
// index that edge i will go to when the Megaminx becomes solved. 
//Therefore the entries in perm are the numbers 09 in some 
// perm m ted order, 
int perm[10]; 

for (int i = G; i < ID; i++] 
perm[i] - 0: 

// South Equator edges 

for (int i ~ 0: i < CMegaminx:: kNumSciuthEqEdges; i++) 

t 

CMegamimc; !color_t cO = 

fMega . EdgeFaceletColor {fMega, kSnuthEqEdgeLli] . 
fMega ,kSouthEcjEdgeR[i]); 

CMegaminx::color_t cl = 

fMega*EdgeFaceletColor(fMega.kSouthFqEdgeR[i] t 
fMega.kSouthEqEdgeL f i ]) : 
permfi] = FarityLookup(c&* cl); 


// South Pole edges 

for (int 1 = 0; i < CMegaminx::kNumSoUthFo!eEdges; 1++) 

I 

CMegaminx;:eolor_t eO = 

fMega *EdgeFaceletColor(fMega *kSouthPoleEdgeM[i)* 
fMega.kSouthPoieEdgeSli]); 

CMegaminx::color_t cl * 

fMega.EdgeFaceletColar(fMega.kSouthPoleEdgeS[i]♦ 
fMega,kSouthPoleE4geN[i]): 
perm[1 + 5] ■ FatityLookup(cO, cl); 


// Now figure out die parity of j>enn 
bool bVisitedPerm[lQ]; 

// indexed same as perm; whether we 
// have counted tliat transition 
int cycleLengths = 0; //sum of (qele length 1) 

for (int i = 0; i < 10: i++) 
bVisitedPerm [i] = false: 
for (int i - G; i < IQ: i++) 

I 

if (bVisitedPerm[i]) 
continue; 

// follow the cycle .starting at perm[il 
int next * i; 

while (IbVisitedPerm [next] ) 

I 

cycleLengths++; 
bVisitedPerm[next] = true; 
next - perm[next]: 

I 

cydeLengths-; 


bool bEvenFarity = ((cydeLengths & 1) = 0): 
return bEvenFarity; 


// look up the correct Southern edge for these colors; returns 
// index into SouthEq tabic, or index + 5 into SouthPole table 

int CSolver::ParityLookup(CMegaminx::eolar_t cO* 

CMegaminx;:color_t cl) 

I 

for (int i - 0: i ( CMegaminx: :kNumSouthEqEdges; i++) 

I 

CMegaminx;:color_t trialColorO = 

CMegaminx::CorrectColor{CMegaminx::kSoutbEqEdgeL[i]): 
CMegaminx;:cQlor_t trialColorl = 

CMegaminx:;CorrectColor(CMegaminx::kSoutbEqEdgeR[ i ]) ; 
if ((cD = trialColorO && cl — trialColorl} | 

(cl = trialColorO && cO ~ trialColorl)] 
return i: 

I 

for (int i = 0; i < CMegaminx;ikMumSouthPoleEdges; i++) 

I 

CMegaminx::color_t trialColorO = 

CMegaminx;:CorrectColor(CMegaminx::kSouthFoleEdgeH[i]); 
CMegaminx::color_t trialColorl = 

CMegaminx;:CorrectColor(CMegaminx::kSouthPoleEdgeS[i]) : 
if ( (cO = trialColorO ^ cl = trialColorl) || 

Cd — trialColorO && cO — trialColorl)) 
return i + 5; 

1 

asset t (false)// trouble,no match 
return 0; 

» 

^pragma mark Solution Steps «“ 

ilttttiiliilttimtlillliittiliittliiMliitiilttllittlliiUlltlUftii 
// Solution Steps 
///////^ 

void CSolver::Stepl() 

I 

Step3Edges{); 

Step3CornerE{); 

SteplVerify0; 


void CSoive r::StepiEd ges() 

I 

for lint i - 0; 1 < CMegaminx::kNumNorthPaleEdges; i++) 

I 

CMegaminx::face_t destFaceN “ 

CM egarninx;tkNorthPoleEdgeN[i]: 

CMegaminx:;faee_t destFaceS = 

CMegaminx::kNorthPaleEdgeS[i]; 

if (fMega.IsEdgeCortect(destFaceN, destFaceS)) 
c ont i nu e ; // already done! 

// if not the correct colors, find an edge that does have 
// [he correct colors and drop it to the South Pole 
// the return value is the South Equatorial luce where 
// it got dropped 

CMegaminx:;color_t cO = fMega.CorrectColor(destFaceNl : 
CMegaminx;;color_t cl = fMega.CorrectColor(destFaceS); 
CMegaminx::face_t southPoleFece ” $tep3_4Drop(cO* cl): 

// now loft it Ixirk to the North Pole; first rotate 

// the South Pole so the edge touches the "down right" face. 

CMegaminx;:face_t rotToFace “ 

CMegaminx::kFaeeDownRight[destFaceS] : 
int diet - Distance(southPoleFace, rotToFace); 

fMega.Slice(kSouthPoleface, CMegaminx::eCounterCW. diet); 
fMega,Slice(TotToFace, CMegaminx::eCW* 2); 
fMega,Slice(destFaceS, CMegaminx::eCounterCW, 2); 

// if the edge is not correctly oriented we need 
if to reorient tt 

if (fMega.EdgeFaceletColor(destFaceN* destFaceS) 1“ 1) 

I 

fMega*Slice(destFaceS* CMegaminx;:eCounterCW, 2); 
int nextSouthFace “ fMega.NextSouthEqFace(rotToFace) ; 
fMega.Slice(nextSouthFace. CMegaminx::eCW. 1); 
fMega.Slice(rotToFace, CMegaminx::eC¥* 1]* 
fMega*Slice(destFaceS. CMegaminx;:eCounterCW. 2); 
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I 

// returns face we dropped it to 

CMegaminx: :face_t CSolver: :Step3_4Drop (CMegaminx: :color_t cQ t 
CMegaminx; :calor_t cl) 

I 

FMega .WriteComment{ fl Step3„4Drop"); 

// search the lower edges for one having these colors 
H (in either order), and if found move it to 
// the South Pole. 

bool bFound - false: 

CMegaminx::face_t southFoleFace “ Or 

// edge dropped to this faceSouthPole 

H search the South Pole edges, and if found we are done! 

if (IbFound) 

1 

for (int i “ 0: i < GMegaminx::kNumSouthPoleEdges && 
IbFound; 

i++) 

t 

CMegaminx;:face_t trialFaceN ■ 

CMegaminx::kSouthPoleEdgeN[iJ ; 

CMegaminx:;faCfi_t trialFaceS = 

CMegaminx::k5outhPoieEdgeS [i]r 
if (fMega.EdgeUasColortf(trialFaeeN. trialFaceS. eO. 

cl)) 

i 

f Mega. Writ eCotnmeni (”Stepl_4 E top found on South 

Pole"); 

bFound = true: 
southFoleFace ” trialFaceN; 

I 

l 

l 

// search the South Equator edges, and if found drop 
// the edge to the South Pole by rotating its left face 
if CW I 

if (IbFound) 

\ 

for (int i * 0: i < CMegsmiimt:kNumSfcuthEqEdges && 
IbFound; 

i++) 

I 

CMegaminx;:face_t trialFaccL = 

CMegaminx::kSouthEqEdgeL[i]; 

CMegaminx::face_t trialFaceR = 

CMegaminx; : kSouthEqEdgeR [1 j ; 

if (fMega.EdgeHasColarsftrialFaceL* trialFaceR. cO. 

cl)} 

{ 

fMega, WriteConment ( ,t Step3_4Erop found on South 
Equator"); 

bFound - true; 

fMega.Slice(trialFaceLt CMegaminx::eCW. 1): 
southFoleFace = trlalFateL: 

I 

I 

1 

// search the Middle Equator edges, and if found drop 
// the edge to the South Pole by rotating its S face 
// either CW 2 or CCW 2 

if (IbFound) 
f 

for (int i - 0; i < CMegaminx: :kNumMiddleEqEdges && 
IbFound; 

i++) 

I 

CMegatninx : :face_t trialFaceN « 

CMegaminx: :kMiddleEqEdgeN[i] ; 

CMegaminx; :face_t trialFaceS ■ 

CMegaminx::kMiddleEqEdgeS[i] ; 

if (FMega.EdgeHasCGlors[trialFaceN, trialFaceS. cQ. 

cl)) 

I 

fMega.VriteComment("Stepl^Drop found on Middle 
Equator")t 


bFound = true: 
southFoleFace E trialFaceS; 

// even indices are below and right of N face, 

// therefore above and left of S face 

if ((IS 1) = 0) 

( 

// above and left, so use CCW 2 

fMega + Slice(trialFaceS* CMegaminx::eCounterCW, 2); 
I 

else 

I 

// above and right, so use CW 2 

fMega.Slic e(trialFaceS, CMe gaminx::eCW. 2); 

I 

1 

I 

\ 

ff search the Nortf i Equator edges, and if found there drop to the 
// South Pole .The Meffert solution uses a simple transformation 
// in case 3 and a complicated one in case i (where It has to avoid 
// disturbing other North Equator edges), but we will use the 
if complicated one tn both cases because the implementation 
// is easier 
if (IbFound) 

[ 

for (int i = 0: 1 < CMegatninx: :kNumNarthEqEdgea: i++) 

{ 

CMegaminx:;fsce_t trialFaceL = 

CMegatninx::kNorthEqEdgeL[i] : 

CMegaminx::face_t trialFaceR = 

CMegatninx: :kNorthEqEdgeR[i] : 

if (fMega.EdgeHasCoiors(trialFaceL. trialFaceR. cD. 

cl)} 

I 

fMega. Write Comment ("Step3_4Drop found on Worth 
Equator”): 

bFound =» true: 

// drop to down left 
southPoleFace ■ 

CMegaminx::kFaceBownLeft[trialFaceL]: 

fMega.Slice(southFoleFace. CMegaminx::eCounterCW. 

1 ); 

DoLUUftrialFaceL, trialFaceR); 

DoLUU(trialFaceL, trialFaceR); 

[Mega.Slice(southPoleFace, CMegamitix: :eCW, 1); 
DoRUUCtrialFaeeU trialFaceR); 

DoRUUCtriaIFaceL, trialFaceR); 

// m this point the edge Is at the upper left of 
// south Pole Face, mi rotate it to pm il on the 
ff South Pole 

fMega,Slice(southFoleFace, CMegaminx::eCounterCW, 

2 ); 

1 

1 

I 

// search the North Pole edges, and if found drop to the 
if South Pole. (This code should only be execute for Step 5. 

H because in Step a die North Pile edges have already been 
ff set and we should have found the desired edge before now.) 

if (IbFound) 

I 

for (int i = 0; i < CMegaminx;;kNumNorthPoleEdges; i++) 

E 

CMegaminx::face_t trialFaceN = 

CMegaminx::kNorthPoleEdgeNU]; 

CMegaminx::face_t trialFaceS * 

CMegaminx:ikNorthPoleEdgeS(i] ; 
if [fMega.EdgeHasColors(trialFaceN* trialFaceS, cG, 

cl)) 

\ 

fMega. WriteCommer]t( ,, Step3_4Drop found on North— 

Pole"): 

bFound - true: 
southPoleFace = 

CMegaminx::kFaceDovnRigbt[trialFaceS]; 

fMega,Slice(trialFaceS. CMegaminx::eCW. 2): 
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2 ); 


fMega. Slice (southPoleFace, CMegatninx: : eCounterCW, 


I 

I 

] 

assert(bFound); 
return southFoleface; 


void CSolver::Step3Corners{) 

[ 

for {CMegaminx::vertex_t destCorner = 0: destCorner ( 5; 

destCornex++] 

t 

// maybe comer is already done! 

if (fMega.IsCornerCorrect(destCorner)) 
continue; 


// top color at left 

// NOTE: Meffert solution wrongly states to use 
// LUU in this case. 

DoRUU(leftFace, rightFace); 

) 

else if (fMega , CornerFacelistColor(rightFace, leftFace, 

bottomFace) =“ I) 

l 

// top color at right 

BoLUU(leftFace. rightFace) : 

] 

else 

I 

// top color at bottom 

DoLUU(leftFace, rightFace); 

DqLUIJ (leftFace, rightFace) ; 

DoLUU (leftFace, rightFace): 

} 

I 


fMega.WriteComment("Step^Corners") : 

// find the corner that should be here, and drop 
// it to the South Pole and move it into place 
CMegatnim: :color_t destcG = 

fMega , Corrected or (CMegaminx: :kCornerFaces[destCorner] [0] J : 
CMegaminx::color_t destcl =* 

fMega,CorrectCalor(CMegaminx::kCornerFaces[destCorner][I]}: 
CMegaminx;:color_t destc2 = 

fMega, CorrectColor(CMegaminx;:kCornerFaces [destCorner] [2]): 
CMegaminx::vertex_t srcCorner = 

fMega.CornerHavingColors(destcD, destcl* deste2); 

// special transformation if the sre is at the 
// North Pole 

if (fMega . IsNorthPolcVertex (srcCorner) J 

l 

fMega,WriteComment["SteplCarners drop North Pole 
corner"); 

CMegaminx;;face_t faceL = 

CMegaminx::kCornerFaces[srcCorner][1]; 
CMegaminx;:face_t faceR = 

CMegaminxi j kCornerFaces[srcCorner][2]; 
DoRUU(faceL„ faceR); 

s rcCorner 5 ; // comer has dropped to North Equator 


// drop the corner to the South Pole (if it Is not 
// already t he re) 

if (fMega , IsNorthEq ua tor Vert ex (srcCorner)) 

{ 

fMega.Slice(CMegaminx::kFaceBelow[srcCorner], 
CMegaminx::eCW, 2): 

srcCorner +=10; // corner has dropped to South Pole 

1 

else if (fMega . IsSouthEquatorVertex(srcCorner)) 

[ 

fMega, Slice {CMegaminx::kFaceBelow[ s rcCorner]. 

CMegaminx::eCW, 1): 
srcCorner i= 5; 


// rotate the vertex into place 

int moveToCorner - destCorner ■+ 15: 

Int dist = Distance(srcCorner, moveToCorner); 
fMega. Slice (kSotithFolePace , CMegaminx:: eCW. diet); 

// lift the vertex into place on the North Equator 

int bottomFace - CMegaminx;:kFaceBelow[destCorner + 5]; 
fMega. Slice(bottoitiFace . CMegaminx::eCounterCW, 2): 


// figure out the orientation and apply the correct 
// transformation to lift it to the North Pole 

CMegaminx: :faee_t leftFace - 

CMegaminx;;kFaceBelow[destCorner] ; 
CMegaminx::face_t rightFace = 

CMegaminx::PrevNorthEqFace(leftFace); 
if (fMega.CornerFaceletC-olor(leftFace. rightFace. 
hottoraFace) 

= 1) 


( 


tiiffifiiifiiiiffmffliitfiiftitiflliiifiiitfntiiiifiifiittiitUJf 

// Step 4. Setting the northern equatorial edges 

// 

//Very similar to Step 3 edge ease; the common 3„4 routine does 
// most of the work. 

void CSolver:;Step4{) 

[ 

for (int i - 0: i < CMegaminx;:kNumNorthEqEdgee: 1++) 

l 

CMegaminx::face_t destFaceL = 

CMegaminx::kMorthEqEdgeL[i]: 

CMegaminx::face_t destFaceR = 

CMegaminx;;kNorthEqEdgeR[i]: 

if (fMega.IsEdgeCorrect(destFaceL, destFaceR)) 
continue: //already doneF 

// if not the correct colors, find an edge that docs have 
// the correct colors ;ind drop it to the South Pole. 

// the return value is the South Equatorial face where 
// it got dropped, 

CMegaminx::coior_t cD = fMega.CorrectColor(destFaceL) ; 
CMegaminx::color_t cl = fMega.CorrectColor(destFaceR): 
GMegafflinx: :face_t southFoleFace =* Step3_40rop(cQ., cl); 

// now loft it back to the North Equator 
// figure the face we want to be under, and 
// rotate the South Pole rogc; there.The 
// desired face Lies directly underneath the 
// desired edge, and therefore below anti left of 
// the desdiceR. 

CMegaminxface_i rotToFace = 

CMegaminx;:kFaceDownLeftIdestFaceR]: 
int diet = Distance(southFoleFace. rotToFace); 
fMega.Slice(kSouthFoleFace, CMegaminx;:eCounterCW, dist); 

// rotate rotToFace eiliter CW 2 or GCW 2 to bring 
// the edge adjacent faceL or face It; we pick the 
// rotation so that the facelet on the face 
// has the face color.'This facelet is currently 
//on the South Pole face. 

// Finally well move it into the correct edge. 

// 

//We combine the CW 2 and CCW 1 to get CW I, and 
// similarly. 

int faceietColor = fMega.EdgeFaceletColor{kSouthPoleFace, 
rotToFace); 

if (faceletColor — destFaceL) 

[ 

fMega. Slice(rotToFace, CMegaminxt;eCW, 1): // = CW 2 

and CCW I 

BoLDgfdeStFsceL, deatFaceR); 

DoLUU(destFaceL. destFaceR); 

fMega.Slice(rotToFace, CMegaminx;:eGW, 1): 

DoRUU(destFaceL. destFaceR); 

DoRDU(destFaceL. destFaceR); 

1 

else 

[ 

fMega.Slice(rotToface, CMegaminx::eCounterCW. 1): 

// = CCW 2 and CW I 
DoRUU(destFaceL, destFaceR): 
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BaRUU(destFaceL. destFaceR): 

fMega.Slice(rotToFace P CMegaminx::eCounterCW , 1): 
DoHJU(destFaceL, destFaceR}; 

DaU11J (destFateL. destFac eR ); 


I 

Step4Veri£y(}; 


OSX 

Mac OS . -9.x 
Windows 95-2000 



itwiiiiiiiiiitiiiiiiiiiitiiiiiiiMiiiiiiiiiiiiiiiiiiiiiiimm 

II Step 1 Setting the northern equatorial corners 

iiiillliiiiiiiiiiiiiiiiiiiiiiiiuiiiiiiiiiiiiiiiiiiiiiiiiuiiiitiliui 

11 

II We step through the vertices, Ending the correctly-oriented 
II comer that belongs thereTo transfer the corner, drop it to 
II the South Pt>!t\ rotate, then rotate up to the North Equator. 

void CSolver::Step5 [) 

( 

for (int destVertex * CMegaminx;:kFirstNotthfiqVertex: 
destVertex <= CMegaminx::kLaetNorthEqVertex; 
destVertex++) 

[ 

if [fMega,IsCornerCorrect(destVertex)) 
continue; II already OK, skip this one 

II Find the corner whose colors should be moved here. This 
II may lx.- the same corner, if it is not oriented correctly 

int cO = 

fMega.CorrectColor(CMegaminx;:kCornetFaces[destVertex][0 ])1 
int cl “ 

fMega.CorrectColor(CMegaminx::kComerFaces[destVertex] [1]); 
int c2 = 

fMega.Correct Co lor(CMegaminx::kCornerFaces[destVertex] [2]); 
int srcVertex = fMega.Cbr&erHavingColots(cO, cl* c2); 
if [srcVettex != de&tVerttx] 

3tep5FlaceVertex{srcVertex, destVertex): 

Step5OrientVertex(destVertex): 

I 

StepSVerify(}; 

1 

II place ;md position the srcVertcx into the destVertex 

void CSolver; 1 5tep5PlaceVei:tex(int srcVertex, int destVertex) 

I 

II drop die sre to the South Pole if needed 

int southPoleFromVertex 3 srcVertex: 
if (fMega.IsNorthEquatorVertex(srcVertex)) 

I 

fMega .tfriteComment O'StepiPlaceVertex from North 
Equator"): 

aouthPoloF tomVertex = srcVertex + 10; 

fMega,Siice .{CMegaminx::kFaceBeiow[arcVertex]. 

CMegaminx::eCW. 2): 

f 

else if (fMega.IsSouthEquatorVertex(srcVertex) ) 

( 

// moving this vertex also disturbs the North Equator 
II vertex on this fece. which might already he correctly 
// placed, so we must rotate the face back after all 
// movements are done.We will handle this by 
II rotating the South Pole face ComuerCW by I and 
II then reversing the face rotation. 

fMega.WriteComment( M Step5FlaceVertex from South 
Equator"): 

southFoleFroraVertex = srcVertex + 5; 

int rat2Face ~ CMegaminx::kFacsBelow(srcVertex]: 

fMega.Slice(rot2Face, CMegaminxeCW* 1): 

fMega,Slice(kSouthPaleFace,CMegaminx;:eCounterCW, 1); 

fMega*Slice(rot2Face. CMegaminx:;eCounterCW, 1); 

1 

II figure where we need to rotate South Pole- to, ;tnd the 
// face to notate CoimterCW to loft to final position 

fMega.WriteComment( 11 StepiPlaceVertex move vertex into 
place"); 

int aouthPoleToVertex = destVertex + 10; 
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// rotate the South Pole CW into position 

int dist = DistanceCsouthPoleFromVertex, 
SOUthFoleToVertex ): 

fMega.Slice(kSouthFoleFace, GMegaminx::eCW, dist); 
// raise the sre into the dest 

int homeFace = GMegaminx;:kFaceBelow[deatVertex); 
fMega,Slice(homeFace, CMegaminx?teCounterCW, 2); 


void CSolver::Step50rientVertex(int destVertex) 

\ 

fMega.WriteComment ["SlepSOrientVertex”); 

// orient the corner, if needed 

// figure the colors of the comer faedets and see if 

// we need to route the comer 

CHtegaminx:;face_t belowFace = 

GMegaminx;;kFaceBelow[destVertex]; 

GMegaminx::color_t belowColor = 
fMega.CorrectColor(belowFace): 

// color of bottom face 
GMegaminx::face_t rightFace = 

GMegaminx:tkFaceAbove[destVartex]: 

GMegaminx:; face_t leftFace = 

GMegaminx::NextNorthEqFacefrlghtFace): 
if [fMega.CornerFaceletColor(leftFace, rlghtFace, 
belowFace) — 

belowColor) 

f 

fMega.SiicefbelovFace, GMegaminx: ;eCW, 2): 

fMega,Slice(kSouthFoleFace, CHegaminx: : eCounterCW, l) ; 

fMega.Slice(belowFace. CM*garninx::eCW* 2): 

) 

else if (fMega..CornerFaceletColor[rlghtFace, belowFace. 

leftFace) = belowColor) 

I 

fMega,SIice(belowFace, GMegaminx;leCounterCW. 2); 
fMega,SIice(kSouthFoleFace. GMegaminx::eCW. 1); 
fMega.Slice(belowFace* GMegaminx:reCounterCW. 2); 


litMiiifiiiiiiiiiiiiftfiUiiiiiiuiliiinniitittttufiittiiiilllliu 

// Step (t. Setting the middle equatorial edges 

//////////W///////////////////////////////////////////////////////// 

// 

//We step through the middle equatorial edges, checking to see if 
// each already has the correctly positioned and placed edge, and if 
// not I hen searching the South Pole edges, the South Equatorial 
// edges, and finally the middle equatorial edges (alter rhis one) 

// for the needed edge. Note that each combination of colors has 
// two edges with this combination, and (1 think) they art' 

// interchangeable; this is unlike the situation for corners, where 
// there are also two comers with a given combination, hut they 
// have opposite orientations and are not interchangeable 
void CSolver::Step&(] 

I 

for (int destFacelndex = 0; 

destFacelndex < GMegaminx::kNumMlddleEqEdges; 
d es t Fac e I nd ex+4) 

I 

GMegaminx:;face_t faceS = 

GMegaminx::kMiddleEqEdgeS[destFacelndex]: 
GMegaminx:;face_t faceN - 

GMegaminx::kMiddleEqEdgeN[destFacelndex]; 

If (FMega.IsEdgeCorrect(faceS, faceN)) 
continue: // already correctly placed and positioned 
GMegaminx::coI d r_t neededColorS = 
fMega, Co rr ec t Color(faceS): 

GMegaminx:: color_t neededColorN = 
fMega.CorrectColor(faceN): 
bool bFound = false: 

// search tile polar edges 

for (int i — 0: 

1 < GMegaminx::kNum£butbPoleIdges && 1bFound: i++) 

I 

GMegaminx::face_t searchPoleFace = 

GMegaminx::kSouthPoleEdgeN[i]; 

If (fMega,EdgeHasColors(kSouthFoleFace. searchPoleFace, 
neededColorS, neededColorH)) 


bFound = true; 

fMega,tfriteCoRimentCStepb move from South Pole"); 
StepGFlacePoleEdge(searchPoleFace. destFacelndex): 


// search the Southern Equatorial edges 

for (int i = 0: 

i < GMegaminx::kNnmSouthEqEdges &£r ibFound: i++) 

I 

GMegaminx:;face_t searchEqFaceL - 
GMegaminx;: kSouthEqEdgeL [1]: 

GMegaminx::face_t searchEqFaceR = 

GMegaminx::kSouthEqEdgeR[i]; 
if (fMega.EdgeHasColors(searchEqFaceL* SearchEqFaceR. 
neededColorS t neededColorN)) 

I 

bFound = true; 

fMega.WriteComment( n Steps move from South 
Equatorial"); 

DoRLL (searchEqFaceR,* searchEqFaceL); 
StepGPlacePoleEdge(searchEqFaceR, destFacelndex): 

1 


// sejirch the (this or later) middle equatorial edges 
// we don't search earlier ones because they are already 
// correctly placed and we don't want to steal from them; 

// we do need to search the edge itself because it might 
// have the correct colors hut wrongly placed, 
for {int searchlndex - destFacelndex: 

searchlndex < GMegaminx::kNumMiddleEqEdges && 

IbFound: 

searchlndex+f) 

t 

GMegaminx::face_t mFaceS “ 

GMegaminx;:kMiddleEqEdgeS[searchlndex] : 
GMegaminx::face„t mFaceM - 

GMegaminx::kMiddleEqEdgeN[searchlndex] : 
if (fMega.EdgeHasColors[mFaceS. mFaceN. neededColorS, 
neededColorN)) 

I 


bFound - true: 

fMega.WriteCotunent1"5tep6 move from Middle 
Equatorial"); 

// lift the found edge, cither right or left. 

// lifting uses the same transformations ns 
U dropping, however the lifted edge goes to the 
// adjoining face. 

if [(searchlndex & 1) = 0) 

f 

// even index, so edge is below and to right, 

// and will be lifted to next face 
GMegaminx::face. I nextMEace = 
fMega.,NextSouthEqFace(mFaceS); 

DoLUU(mFaceS, nextMFace}: 

DoLLL{mFaceS, nextMFace): 

DoRDU(mFaceS, nextMFace): 

Step6PlacePoleEdge(nextMFace, deatFaceindex); 

I 

else 


// odd index, SO edge is below and to left, 

// and will be lifted to previous face 
GMegaminx:;face.t prevFace = 
fMega.PrevSouthEqFact*(mFaceS): 

DoRGU[prevFaca, mFaceS); 

DoRLL{prevFace h mFaceS): 

DoLUU(prevFace, mFaceS)j 

Step6PlaceFoleEdge(prevFace. destFacelndex): 

1 

1 


assert(bFound); 

I 

bool bEdgeFarityOK = CheckEdgeParityO; 
if UbEdgeParityGK) 

I 

// take evasive action; we will swap two same-colored 
// edges in The equator.This b a transposition, so 
// it should cause the edges in the South half to 


38 


MacTech • June 2(K)2 









CCOCOA 


Subscribe) 

TOW\Y! 



IhTm 

"»" J | n l ■ 


jhgf 

■i T j iji 

H *Ji 

Kite 






















// switch to even parity. We'll somewhat arbitrarily 
// swap the two 14 color edges, located at 2-It) 

// and 4-8. Just as in earlier Step (\ work we move one 
// edge to the South Pole, place it correctly which 
// moves the other edge to the South Pole, then place 
// that edge. 

fMega.WriteComment("Step6 evasive action to fix 
parity 1 ') ; 

DoLUU C10. 11): // move 2 -10 to South Pole 

DoLLLdO, 11); 

DoRUtl (10. 11); 

fMega.Slice(kSmithPaleFace» CMegaminx;:eCounterCW. 2); 

// position 

Do RUU ( 1 2, 8) ; // move 2- 1 0 to equator,4-8 to South Me 

DoRLL[12. 8): 

DoLUU(12 i 8): 

fMega . Slice (kSou thPol eFac e , CMegaminx:: eCW . 2): // petition 

DoLUU(10. 11); // move 4-8 to equator 

DoLLLMO, 11); 

DqKUUUO, 11); 

) 

StepGVerify [); 

I 

void CSolvcr::StepfiPlacePoleEdge(im fromSFace, int 
toEdgelndex) 

E 

// rotate the edge CounterCW to the correct position 
fMega.WriteComment("StepePlacePoleEdge"); 

CMegaminx:;face_t ToSFace = 

CMegaminx::kHiddleEqEdgeS[toEdgeIndex]; 
int dist = Distance(fromSFace, toSFace] ; 
fMega.SliceCkSouthPoIeFace, CMegaminx;:eCotmterCW. dist); 

// flip the edge if it is wrongly oriented 
CMegaminx;:faee_t nextFace = 
fMega.NextSDuthEqFace(toSFace): 

if (fMega.EdgeFaceletColor(toSFace, kSouthfoleFace) !- 
fMega.CorrectColor(toSFace)) 

I 

fMega . WriteComment ("Step&PIacePcileEdge flip edge 11 }; 

DoRLL(toSFace* nextFace); 

fMega,Slice[kSouthFoleFace. CMegaminx::eCW, 1); 

1 

// now drop it into position, either on left or right 

CMegaminx;:face_t prevFace = 
fMega.FreySouthEqFace(toSFace); 
if ((toEdgeIndex & 1) — 0) 

t 

// even index, so edge Ls below and to riglu 
DoLUU(toSFace. nextFace}: 

DoLLL(toSFace. nextFace) ; 

DoRUU(toSFace, nextFace) : 

1 

else 

( 

// mid index, so edge is below and to left 

DoRUU(prevFace. toSFace); 

DoRLLfprevFace, toSFace): 

DoLUU(prevFace, toSFace); 

I 

\ 

uiiiHiittiiiiiiiiiiHiihniiffiiiiiiiiiittiiunifiuuiummm 
if Step 7. Setting the Southern Equatorial Edges 
tiifitiiiimitftifiiffiitziiiiifitifiiuiiumiiaiiiiiimfiififiu 
// 

void CSolver::Step?0 

[ 

for (int i ~ D; i < GMegaminx: ikNumSmithEqEdges; i++) 

CMegaminx:;face_t destFaceL = 

CMegaminx:ikSonthEqEdgeL[i]; 

CMegaminx::face_t destFaceR — 

CMegaminx:;kSouthEqEdgeR[i]; 

if (fMega.IsEdgeCorrect(destFaceL. destFaceR)) 
continue: 

CMegaminx:;colar_t destColorL * 
fMega *CorrectColor(destFaceL); 

CMegaminx::colot_t destCoiorR - 


fMega.CorrectColor(destFaceR); 

// dieck to sec if needed color is on South Pole 

bool bFound = false; 

for (int j = 0: j < CMegaminx;:kNumSouthPoleEdges && 

! bFound: 

t*) 

1 

CMegaminx::face_t srcFaceN = 

CMegaminx::kSouthFoleEdgeN[j]; 

CMegaminx:;face_t srcFaceS = 

CMegaminx;:kSauthPoleEdgeS[j]; 

if (fMega.EdgeHasColors(srcFaceN. srcFaceS, 
destColorL. 

destCoiorR)) 

i 

bFound = true; 

Step7FlacePoleEdge(srcFaceH, destFaceL* destFaceR); 

I 


// check if needed color Is on South Equator; do not 
// check already-placed edges 

if (1bFound) 

1 

for {int j = i; j < CMegaminx: :kMumSouthEqEdges && 

! bFound; 

j++) 

I 

int srcFaceL = CMegaminx;:kSouthEqEdgeL[jJ : 
int srcFaceR = CMegaminx;:kSouthEqEdgeR[j]: 
if (fMega♦EdgeHasColors(srcFaceL, srcFaceR, 
destColorL, 

destCoiorR)) 

I 

// loft the edge using RLi, so it goes above srcFaceR, 

// then move to correct place (remember that we are 
// Rooking at the Mcgaminx upside down, so the 
// left (bee is srcFaceR) 
bFound = true; 

fMega. WriteComment ("Step? loft edge 11 ): 

DoRLL(srcFaceR. srcFaceL): 

Step7PlacePoleEdge(srcFaceR. destFaceL* 

destFaceR); 

) 

! 

1 

assert(bFound): 

J 

Step7Verify(); 

1 

// place an equatorial edge that is currently on the pole; 

// eqFace is the equatorial face it is below, 

void GSolver::Step 7PlacePoleEdge(CMegaminx::£ace_t sreFaceM. 
GMegaminx::face_t destFaceL, 

CMegaminx::face_t destFaceR) 

I 

U find the face It belongs to and rotate it there; 

// find the CW distance we should move; we move it so 
// its equatorial color matches the destination face color.Then 
// lift it into position using RLL or ILL. Remember we measure 
// right and left with the Mcgaminx right side up. 
fMega. Write Comment ("STepiPlaceFoleEdge"): 

CMegaminx;:eolor_t destFaceGolor = 

fMega.EdgeFaceletColor(sreFaceM, kSouthPoieFace); 
bool bLiftFromLeft " 

(destFaceColor =■ fMega.CorrectGolor(destFaceL)); 
CMegaminx:;face_t destFace = 

bLiftFrontleft ? dsstFaceL : destFaceR; 
int dist = Distance(destFace, sreFaceM); 
fMega.Slice(kSouthPoieFace t CMegaminx;:eCW, dist); 
if (bLiftFromLeft) 

DoRLL(destFaceR, deetFscnL); 
else 

DoLLL(destFaceR, destFaceL): 


litiiiittuiiiiuiiiiiiuiitintiiiiiiiltftimilftiitiliilfifitiiiut 

U Mep 8. Setting the South Pole edges 

fiiiiiiliuiitlfifiiliflilffiiifflliiiiiiifiuuiimifiiiiuiuuiui 

a 

if 'Ibis step both positions and orients the South Pole edges. 
// 


40 


MacTech * June 2002 








MacDirectory Magazine 

Creative designers, writers, musicians, business leaders and our expert 

TECHNOLOGY TEAM OFFER THEIR OWN PERSONAL INTERPRETATION OF THINGS THAT 

only the Macintosh system can deliver. Featuring over 240 paces of 

REVIEWS, PRODUCT NEWS, INSIGHTS, TRENDS AND THE LARGEST MACINTOSH BUYERS' 
GUIDE - INCLUDING OVER 5,000 PRODUCTS AND SERVICES FOR YOUR MAC. 

Interviews 

Tapping into the world of celebrities and their macs, only MacDirectory 

OFFERS IN DEPTH INTERVIEWS- GET A CLOSE AND PERSONAL VIEW ON STEVE JOBS, 

Tom Cruise, Claudia Schiffer, Madonna, George Lucas and other leaders in 
the Mac community. 


Culture 

MacDirectory takes you to the wildest corners of the close and uncov- 
Efts many uses of Macintosh computers. Travel to Japan, Australia, Germany, 
India, Brazil, Russia and learn more about Apple’s cultural impact around 

THE GLOBE. 

Subscribe 

Subscribe online for faster delivery; www.macdirectory.com/sub.html 
Subscription rates follows: i year, $32.00 for 4 issues & 2 years, $60.00 for 
8 issues. Or you may also mail a check or money order to: MacDirectory 
Subscription dept. 150 west 25TH st ny ny 10001 . include your phone, 
email and mailing address. 




// Wt: pick a fixed orientation to make the rotation calculations easy. 

//Tiie parked edge in on faces 8 and 9, and we rotate it for lofting 
// to be on faces 7 and 8, so we'll use LLL to loft it. 

// The reference edge is on faces 7 and 10. the second edge is on faces 
// 7 and I fand the third edge is on faces 7 and 12. 

// 

// NOTE: All edge operations must be be done using the fixed 
// edge 8-9, otherwise things won't be properly aligned 
// sifter setting the first 3 edges. 

// 

//We don't have to return the South Pole after each move 

void CSolver;;StepS[) 

I 

Step8ReferenceEdge{): 

StepSSecondEdge(): 

StepSThirdEdgeO; 

StepSRestoreEquatorU; 

StepBOrientFourFive(); 

StepBVerifyO : 

1 

void CSolver::StepSReferenceEdge[) 

( 

if (fMega,IsEdgeCorrect {1 , 10)) 

return: // already correct, no action needed 

fMega , WriteCoaiment ("StepBReferenceEd ge ,f ); 

// place and oriem the reference edge 

// locate the correctly colored edge 

bool bFound = false; 

CMegamlnx::face_Jt srcFace - 0: 

for [int i - 0; i < CMegatiiinxft'kNuiiiSouthPoleE.dges && 
]bFoundi 


srcFace = CMegatninx: :kSouthPoleEdgeN[x] ; 
bFound - fMega.EdgeHasColors(srcFace. kSouthFoleFace, 1, 
4); 

) 

assert[bFound); 

if (fWega.EdgeFaceletColor[kSouthFoleFace♦ srcFace) != 1) 

[ 

// need to orient edge 

// first move the edge over to Hipping area, at face 9 

int diet = Distance(9, srcFace); 

fMega♦Siice(kSouthFoleFace, CMegatninx::eCW H dist); 

// now flip the edge; it will go to lace 8 

Do LLL(3 H 9): 

srcFace ® 8; // pretend it was here all along 
J 

// move the edge into position at edge 10 

int dist = Distance(10 T srcFace); 

fMega.Slice(kSouthFoleFace, CMegSminx::eCW„ dist): 


void CSolver::Step85 econd EdgeC ) 

\ 

if (fMega.IsEdgeCorrect(7, 11)) 
return; // already correct. no acti on needed 

// place and orient the second edge 
if For this operation we have to return the South Me face 
fi to its original position so that the reference edge will 
// be in place. 

// locate the correct color 
bool bFound = false; 

CMegatninx:;face_t srcFace = 0; 

for (int i — 0: i i CMegatninx::kNmnSouthPoleEdges && 

! bFound: 

i+4) 

I 

srcFace = CMegaminx;:kSouthPoleEdgeN[i] : 
bFound = fMega .EdgeHasColors [srcFace. kSouthFoleFace P 1, 
5 ) ; 

1 

// if not found, the desired edge is already parked, so 
// skip the parting 


if [bFound) 

i 

// we will loft using faces 8 and 9, so the South Pole 
// face must be rotated to place aface in one of these 
// positions, but such that the reference edge (face 10) 

// docs not go to either; dds means our CW rotations must 

// be something other than I and 2. 

bool bUseRLL = true; 

int dist * Distance(9, srcFace); 

if [dist = 2} // dist ~ 1 is impossible because that moves 10 to 9 

{ 

dist = 3 ; if rotate to 10 instead 
bUseRLL = false: 


fMega,WriteGoflnnent("StepBSecondEdge parking"); 

GTetnpRotate rotl(fMega, kSouthFoleFace. dist. 

CMegaminx;;eCW); 
if (bUseRLL) //park edge 1 
DoRLL(8, 9); 
else 

DoLLLCB. 9); 

I 

I 

// now move the edge from the parked position to the South Pole 

fMega.WriteComment("StepSSecondEdge placing"); 

{ 

CTempRotate rot2{fMega, kSouthFoleFace, 2, 

CMegaitiinx: :eCounterCW) : 

DoRLL (B, 9) : // places the edge 

// if the edge is not oriented correctly, re orient it 

if (fMega.EdgeFaceletColor(kSouthFoleFace, B) 1= ]} 

l 

fMega.WriteComment("StepSSecondEdge re-orienting"); 
BoRLL(3, 9); 

fMega.Slice[kSouthFoleFace, CMegaminx::eCW, 1): 

DoLLL{8. 9); 

FMega,Slice(kSouthFoleFacp, CMegaminx:;eCounterCW, 1); 
DoRLL(8, 9); 

I 

\ 

J 

void CSolver; :StepSTb'l rdEdge [) 

[ 

if {fMega,IsEdgeGorr art (7 . 12)) 

re turn; // already correct, ru ) act ion n ceded 

// place anti orient the third edge 
// For this operation we haw to return the South Pole face 
// to its original position so that the reference edge will 
// he in place. 

// locale the correct color 
bool bFound = false; 

CMegaminx::face_t srcFace = 0: 

for (int 1=0; 1 < CMegaminx::kNutnSouthPoleEdges && 

IbFound; 

i++) 

I 

srcFace = CMegaminx;: kSouthPoleEdgeNf i] ; 

bFound = fMega.EdgeHasColors (srcFace, kSouthFoleFace , 1, 


// if not found, the desired edge is already parked, so 
// skip die parking 

if(bFound) 

( 

// we wit! loft using faces 8 and 9, so the South Pole 

// face must be rotated to place aFace in one of these 

// positions, but such that the reference edge (face 10) 

// and second edge do not go there either. 

bool bUseRLL = true; 

int dist = 0; 

switch (srcFace) 

1 

case 12: 

( 
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// rotate CountertlW l to face 8, use ILL 
dist = I: 
bUseRLL = false; 

I 

break; 

case 8; 

{ 

// already in place on face 8, use 111 
dist • 0; 
bUseRLL = false; 

I 

break; 

case 9: 

[ 

II already In place on face 9. use RLL 
dist = 0; 
bUseRLL = true; 

I 

break; 

default: 

[ 

assert{false); 

1 

break: 


fMega hW riteComment{"StepSThirdEdge parking"); 

GTempRotate rotl(fMega, kSouthPoleFace. dist* 
CMegaminx::eCounterCW); 
if (bUseRLL) 

DoRLLte, 9 ); 
else 

DdLLL(8, 9}; 

1 


// now move the edge from the parked position to the South Pole 

fMega.WriteComment("StepSThirdEdge placing 1 ') ; 

CTempRotate rot2(fMega, kSouthPoleFace* 1* 

CMegaminx: : eCounterCW] ; 

Do RLL [ 8 * 9); If places the edge 

// if the edge is not oriented correctly, re-orient it 

if (fMega.EdgeFaceletColor(kSouthPoleFace, 8) 1= 1) 

I 

DoRLL(S. 9 ); 

fMega.Slice(kSouthPoleFace. CMegaminx;:eCW, 1); 

DoLLL (8 , 9) ; 

fMega.Slice(kSouthPoleFace, CMegaminxr:eCounterCW. 1); 
DoRLL(8. 9); 

» 

I 

) 

void CSolver:;StepSRestoreEquatorQ 

[ 

// figure out w hich South Pole edge ha* the equatorial edge 
// and restore it to its correct place 

fMega * WriteComment ("StepSRestoreEquator") ; 
if (fMega.EdgeFaceletColor(kSouthPoleFace, fi) t= 1 && 
fMega.EdgeFaceletColar(0. kSouthPoleFace) 1= 1) 

DoLLL (8 , 9); // 7-8 edge should be on equator 
else if (fMega.EdgeFaceletColor{kSouthPoleFace, 9) J= 1 bb 
fMega.EdgeFaceletColor{9, kSouthPoleFace) 1= 1) 

DoRLL [ 8, 9); // 7*q edge should be on equator 


void CSolver:;8tepS0rientFourFive() 

( 

// according to the Mdiert solution, d and 5 will have 
// the correct colors hut might he oriented in turret: dy. 

// check Lhat they have the correct colors. 

assert (fMega.* EdgeHasColors [kSouthPoleFace. 8. I* 2}); 
assert (FMega .EdgeHasColors [kSouthPoleFace , 9, l r 3)); 

// check that everything is correctly oriented 

bool b7SQK = fMega*IsEdgeCorrect(kSouthPoleFace. 8); 
bool b?90K = fMega *IsEdgeCorrect(kSouthPoleFace, 9); 


if (b780K bb b790K3 
r e tu rn; // we' re donel 

If if only one is bad, then the equator is also had, so 
// loft it to the pole first 

fMega. WriteComment f "StepSOrientFourFive lofting"): 
enum Lofting (eNothing ■ 1, eLLL, eRLLI; 

Lofting whichLoft = eftothing: 
if (b780K bb !b790K} 

( 

whichLoft = eLLL; // loft to left 
DoLLL[8* 9); 

I 

else if [!b7SOK bb L790K} 

I 

whichLoft = eRLL: //loft to right; 

DoRLL[8* 9); 

I 

If now the [Disoriented edges :tre on die South Pole; 

If apply the special operation to re-orient them 

fMega.WriteComment {"StepBOrientFotirFive placing"): 
for (itit i = 1; i <- 4; i++) 

I 

DoRLL(8 + 9); 

fMega.Slice(kSouthPoleFace, CMegaminx:;eCounterCW, 1); 

1 

fMega.Slice [kSouthPoleFace* CMegaminx::eCounterCW. 1); 
for (int i - 1; i <= 4; i++) 

I 

DoRLL[8* 9): 

fMega.Slice(kSouthPoleFace * CMegaminxeCounterCW. 1); 

I 

fMega.Slice(kSouthPoleFace * CMegamirex:;eCW * 1): 

If now return tlie equatorial edge if needed 
// NOTE: we do die operation twice; 

// the published Meffert solution Incorrectly shows it 
If only once. 

fMega.WritaCotfflUent("StepSGrientFour?ive returning 
equator"); 

if (whichLoft = eLLL) 

I 

DoLLL(8 r 9): 

DoLLL(8 1 9); 

1 

else if (whichLoft — eRLL) 

l 

DoRLL[8 T 9); 

DoRLL[8* 9); 

I 


ifiiiiiiiiiiiiiiiilllilllllllliillliillliliiiiiiiiiiiiiiiiiiiiiiiuiii 
If Step L 1 Placing the southern equatorial comers 

IlllllilllillUItlltlllliiiliiiillliiiiliiiiliiliiiiiiiiiiiiiiiiiiiifi 

if 

If We swap corners to get the southern equatorial comers correctly 
If plated, Our basic case is when one corner is on the South Pole 
If and one is on the South Equator; we convert the other case 
// (both on South Equator) to the first case by lofting one of the 
If comers to the South Bile, 
void CSolver::Step9{) 

I 

for (CMegaminx;:vertex_t dst = 

CMegaminx::kFirstSouthEqVertex; 

dst <= CMegaminx::kLastSouthEqVertex; dst++) 

l 

if (fMega.1sCornerCorrectlyPlaced(dst)) 
continue; // already OK,so skip 

// find sre, the vertex holding the corner that should be here 
If sre is either on die South Pole or on the Southern Equator 
// 

CMegaminx;:color_t cQ - 

fMega. CorrectColorlCMegaminx::kCornerFaces[dst][D]): 
CMegaminx::color_t cl ~ 

fMega *CorrectColor(CMegaminx::kCornerFaces[dst] [I]); 
CMegaminx:;color_t c2 - 

fMega.CorrectColor(CMegaminx:;KCornerFaces[dst][2]}; 
CMegaminx::vertex^t sre = 

fMega.CornerHavingColors[cO. cl r c2); 
if (sre <= CMegaminx;:kLastSouthEqVertex) 
f 

If sre is on South Equator, so we must loft it 
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// to the South Pole 

fMega.WriteCoxment ("Step 9 lofting"); 
CMegatnlnx: : face_t leftFace * 

CMegaminx:ikCornerFaces [sre][2]; 
CMegaminx::face_t rightFace — 
CMegaminx: : kComerFaces [sre] [l] ; 
DoRLL(leftFace. rightFace): 

DqRLL( leftFace* rightFace); 

DoRLL(leftFace p rightFace); 

sre += 5; //sue is now on the South Foie 

I 

Step9EqoatorAndPole(dst* arc); 

I 

Step9Verify(): 


void CSolver;:EtepSEquatorAndPole{CMegaminx: :vertex_t dst, 
CMegaminx:;vertex_t arc) 

I 

// route the South Pole CCW so sre is directly above dst: 

// we need to route it back when we are finished to avoid disturbing 
// the South Pole edges, 

int dist - Distance(dst + 5* arc): 

fMega. WriteComment {"Step9EquatorAndPole rotating pole”): 
CTempRotate rotl(fMega, kSouthFoleFace. dist, 

CMegaminx::eCounterCW); 

// now swap the vertices 

fMega,WriteComment( u Step9EquatorAndPole swapping”) ; 
CMegaminx::face_t leftFace = 

CMegaminx:ikCornerFaces[dst][2]; 

CMegaminx::face_t rightFace = 

CMegaminx::kCornerFaces[dst] [1]; 

DoRLL(leftFace, rightFace): 

DoRLL(leftFace. rightFace): 

DoRLL(leftFace. rightFace): 


uiitmiiimimiuiiimitiitftiimiummiitimm 

II Step 10. Placement Of the South Pole corners 

iiiifilllfiiiitiiiiiiiittiiitiiiiifiiiitiifiiitiliiitlltttlitttllttlil 

n 

void CSolver::SteplD() 

I 

for (CMegaminx:;vertex_t destCorner = 

CMegaminx;:kFirstSouthfoleYertex: 

destCorner CMegaminx; rklastSouthPaleVertex: 
destCorner++) 

\ 

if (fMega * IsComerCorrectly Placed [destCorner)) 
continue; 


// find the comer that belongs here; do not check 
// already-placed comers. Do not check ihe srcCorner 
// because wc already know it is not correctly placed 
// (we don't do orientation until Step 11), 

bool bFound - false; 

for (CMegaminx; :vertex,! srcCorner 5=1 destCorner + 1; 
srcCorner O CMegaminx;ikLastSouthPoleVertex && 

IbFound: 


srcCorner-H-) 


if (destCorner = 

fMega,CorrectSouthernVertex(srcCorner)) 

l 

bFound = true; 

// now move everybody; we id way rotate to vertex IS. 

// and the left and right laces are 12 and B. 

//We use two blocks so the CTempRotate destructors will 
// rotate back to the original position in between 
II transformations 

fMega .WriteComment ["SteplC”) ; 


II swap srcCorner and 10 

CTempRotate rotl(fMega, kSoutJiFaleFace, 

srcCorner - 15, CMegaminx::eCounterCW): 
DoRUU(12, 8): 

DoRUU(12* E); 

DoRUU(12, 8); 


I 

II swap destCorner and sreCortier (which is now in 10) 


CTempRotate rot2(fMega, kSouthFoleFace. 

destCorner - 15, CMegaminx::eCounterCW): 
DoRUU(12. S); 

DoRUU(12, 8): 

DoRUU(12, 8); 


I 

// restore 10 to its original position 

CTempRotate rot1(fMega. kSouthPeleFace t 

srcCorner - 15, CMegaminx:;eCounterCW): 
DoRUU(12* 8); 

DoRUU(12 t 8); 

DoRUU(12, 8); 


I 

) 

assert(bFound): 

I 

SteplQVerify(); 

I 

tttHltlinfiltimillttllitttiitllilttifftlittiUftiiittiitttiitftut 

II Step 11. Orientation Of the southern equatorial and South Pole comers 

iiiiiiimiifiiiiiifiiuiifiuifiiiifilifiiiiiiifiliiiiuuitiiufuu 

11 

It We find pairs of oppositely-oriented corner pieces that ;irc not 
II correctly oriented, drop them lu the South Pole, then 
// swap them and return them to their original position .They 
If luve to be dropped such that they ate next to each other. 

// We treat the case "neither tin South Pole" as the basic case 
II and transform all others to that: 

// (I) if both are on the South Pole, we pick two separate faces. 

II one holding each comer, and rotate those CCW to drop them 
II to the Southern Equatorial belt. 

// (2) if one is on the South Pole and one not, we route the 
If South Pole so that corner is nor touched the face the other is 
II on. then rotate a face the South Pole corner is on. 

class CSteplICornerVisitor : public CCornerVisitor 

I 

public; 

CStepIlCornerVisitor(CMegaminxi rMega] : 
fMega[rMega), 

fNeedsCounterCWCornerl(-1), fNeedsCounterCWCorner2(-l] , 
fNeedsCWCornerl ( 1). fNeedsCWCorner2 (-1) 

11; 

‘"CStepllCornerVisitor0 II; 

virtual void VlsltCorner(int cornerlndex); 

If member variables these are the vertex indices 

II of comers that need l turn CCW or CW to lie 
II correctly oriented 

CMegaminx::vertex_t fNeedsCounterCWCornerl: 

CMegaminx:;vertex_t fNeedsCounterCWCorner2: 

CMegaminx:*vertex t fNeedsCWCarner1: 

CMegaminx: :vertex_t fNeed&CWCornerZ: 

CMegarninxi fMega: 


void CSteplICornerVisitor:;VisltCorner(int cornerlndex) 

I 

II maybe we are already done 

if (EfMeedsCounterCtfCornerl >= 0) && 

(fNeedsCWCornerl >- 0) ) 
return; 

fl check whether the comer is correctly oriented, 

II and if not. which direction it should l>e turned 

ff face numbers in CCW order 

CMegaminx::face_t fO - 
CMegaminx;:kCornerFaces[cornerlndexi [0]; 

CMegaminx::face_t fl = 

CMegamirEX::kCornetFaces[cornerlndexl [i]; 

CMe-gaminx:: face_t f2 = 

CMegaminx::kCornerFacea(cornerIndex][2]; 

If fuedet color for fee del on face fll 

CMegaminx;;eolor_t cO - fMega,CornerFaceletColor(fD* f 1, 
f2); 
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if (cO = CMegaminx::CorrectColor(f1J) 

[ 

// should turn cc:w 

if CfNeedsCounterCWCarnerl < 0} 

fNeedsCounterCWCornerl = cornerlndex; 
else if (fNeedsCounterCWCorner2 < 0] 
fNeedsColinterCWCornerZ = cornerlndex: 

I 

else if CcO — CMegaminx;:CarrectColor(f2)) 

( 

// should turn CW 
if [fHeedsCWCornerl < 0) 

fNeedsCWCornerl = cornerIndex: 
else if (fNeedsCWCornerZ < 0) 
fNeedsCWCornerZ = cottier Index: 

1 

// otherwise is correctly oriented, do nothing 

! 

void CSolver::Stepl1() 

1 

// the transformation turns one corner CW and one comer CoiinterCW. 
// so ideally we would pick comers that need this to be correctly 
// positioned; however if we don't have such a pair we can pick 
// two with the same positioning, and then one will become correctly 
// positioned and one will be switched to the opposite positioning, 
for (int i - 0: i < 1D0; i++) // break out if stuck in loop 
f 

CStepMCornerVisitor aVisitor(fMega): 

Visit Allcomers t a Visit or) ; 

int vGounterCW = aVisitor,fNnedeCounterCWCorner1; 
int vCW = aVIsitot♦fNeedsCWCornerl; 
if ((vCounterCW < 0) &S EvCW < 0)) 
break; 

// check that we the idea! pairing, and if not double up 
// on die other orientation 

if (vCounterCW < 0) 

vCounterCW = aVisitor♦ fReedsCWCornerZ ; 
elae if (vCW < 0) 

vGW = aVisitor.fNeedsCounterCWComer2; 
assert(vCW 0 && vCounterCW >= 0); 


bool bCounterCWIsOnEquator = 

fMega.IsSouthEquatorVertex(vCounterCW): 
bool bCWIsOnEquator “ fMega.IsSouthEquatorVertexfvCW); 

if (bCounterCWIsOnEquator && bCWIsOnEquator) 

I 

Step]IBothEquators(vCounterCW. vCW); 

else 

[ 

// pick two non-adjaccnt faces for dropping the vertices 
// to the South Equator. If one is already on the equator 
// we don't have to move it. Tf the vertices are directly 
H above each other (one on pole and one on equator), we need 
// to rotate the Soudi Pole first so they can be on 
// non-adjaccnt faces. 

// first check for possibly needed pole rotation 
int spCount = 0: 

if (std::abs(vCounterCW - vCW) — 5) 

i 

// the vertices are above each other, so well 
// rotate the pole 1 CCW 

spCount ” 1; 

if f3bCounterCWIsOnEquator) 
vCounterCW = 

fMega ^ NextCounterCWVertex (kSouthPoleFace. 
vCounterCW); 

else 

vCW = fMega..NexrCoursterCW Vortex (kSouthPoleFace, 

vCW) ; 

I 

// now do any necessary dropping of vertices to the South Equator 

// check counterCW vertex 

int faceCounrerCW - 0, faceCW = 0: 
fKega.FindNonAdjacentSouthFaces(vCounterCW, vCW, 
kfaceCounterCW. ifaceCW): 

int caunterCWCount ” 0. cwCount “ 0; 

int nextCounterCW = vCounterCW, nextCW = vCW; 
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CMegaminx::Direction direetionCounterCW = 

CMegaminx::eCW, 

directiouCW = CMegatninx::eCW : 
if (IbCounterCWIsOnEquatQT) 

I 

counterCWCount = h 

nextCounterCW “ fHega .NextCWVertex (faceCounterCW, 
vCounterCW): 

directionCounterCW = CMegaininx::eCW; 

if (IfMega.IsSQUthEquatorVertex(nextCounterCW)) 

t 

// wrong direction, go in other direction 

nextCaunterCW - 

fMega.NextC o ant e r GWe r t ex{faceCounterCW, 
vCounterCW): 

direetionCounterCW = CMegaminx:reCounterCW: 

l 

I 

// check CW vertex 

if (IbCWIsOnEquator] 
f 

cwCount = 1: 

nextCW “ fMega.NextCWVertex(faceCW, vCW); 
directionCW = CMegaminx::eCW: 
if (IfMega,IsSouthEquatorVettex(nextCW)j 
[ 

// wrong direction, go in other direction 

nextCW - fMega.NextCounterCWVert ex (faceCW* vCW); 
directionCW = CMegaminx::eCounterCW: 

I 

) 

fMega,WriteComment("Step11 non-equator case")? 

CTempRotate rotSouthPole(fMega , kSouthPoleFace, 
spCount, 

CMegaminx: teCountsrCW) : 

CTerapRotate rotCounterCW(fMega, faeeCounterCW, 

counterCWCount, directionCounterCW] ; 
CTerapRotate rotCWtfMega, faceCW, cwCount. 
directionCW): 

StepllEothEquators(nextCounterCW, nextCW); 

) 

I 

I 
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void CSoiver:: StepUBothEquatorsUnt vCounterCtf, int vCW) 

[ 

// we will loft the colors of both vertices to the South Pole; 

// need to Figure out which direction to rotate their faces, 

// am) what rotation is needed for the South Pole to have the 
// lofted comers together 

// pick two non-adjaeent faces for lofting the vertices 
int f a c e Coun t e r CW, faceCW;// laces to rotate 
FMega.FindNonAdjacentSouthFaces(vCounterCW. vCW, 
kfaceCounterCW, kfaceCW); 
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// figure out the direction to rotate each face, and which vertex 
// the corner will loft to 

//We wilJ position the CCW comer I vertex CW of the CW face, 

// and rotate the CW face to put the tlW vertex next to the CCW 
// vertex.The right face will then be the CW face. 

CMegaminx:[Direction dCounterCW, dCW t //directions to loft 
int loftedCounterCWl* loftedCWl; 

loftedCounterCWI = fMega,NextCounterCWVettex f faceCounterCW. 
vCounterCW ); 

if (fMega.IsSouthFoleVert ex(1o ftedCounterCW1}) 

I 

dCounterCW ** CMegaminx:;©CounterCW: 

I 

else 

I 

// wrong direction,go hack in other direction 
dCounterCW = CMegaminx:;eCW; 

loftedCounterCWI = fMega.NextCWVertexffaceCounterCW, 
vCounterCW )i 

l 

Int cwClicks = 0; 

loftedCWl = fMega *NextCWVertex £ faceCW, vCW): 
if (fMega,IaSouthPoleVertex(loftedCWl)] 
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dCW = CMegaminx:: eCW; // OK. at left edge of face 
cvCiicks = 1; 


} 

else 

l 

// wrong direction, go two venkes in other direction 
dCW = CMegaminx::eCounterCW; 

loftedCWl = fMega,NextCounterCWVertex(faceCW, vCW) ; 
loftedCWl = fMega *NextCounterCWVertex(faceCW. loftedCWl); 
cwClicks = 2; 

] 

if now figure out the South Pole rotation 
U we want CCW to be on the left of CW 
// as a simplification we wilj always rotate the South Pole CCW 

int iCountsrCW = -1. iCW 3 -1; 
for (int i * 0; i < 5; i++) 

I 

if (CMegaminx:ikFaceVertices[kSouthFoleFace][i] = 
loftedCounterCWl) 

ICounterCW - i: 

else if (CMegaminx;;kFaceVertices[kSouthPoleFace][i] = 
loftedCWl) 

iCW - i; 

1 

int distToRotate = (iCW 1) ■ iCounterCW: 

if (distToRotate < 0) 
distToRotate += 5: 
if (distToRotate >- 5) 
distToRotate 5; 

// OK. now we are ready to rotate everything! 

int rightFace = faceCW; 
int leftFace = faceCW - l: 
if (leftFace <“ kSouthPoleFace) 
leftFace 4* 5; 

// rotate the comers into place 

fMega♦ W'riteConnnentf 11 Step!iBothEquators lofting") : 
CTempRatate loFtCounterCW(fMega, faceCounterCW, 1, 
dCounterCW); 

CTempRotate southFoleRotate(fMega, kSouthPoleFace, 
distToRotate. CMegaminx;:eCounterGW); 

CTempRotste loftCW(fMega. faceCW. cvGlicks, dCW); 

// do the corner swap 

fMega,WriteComment( w SteplllothEquators corner svap"): 

DoRUtHleftFace* rightFace); 

DoRUU(leftFace. rightFace); 

fMega.Slice(kSouthPoleFace. CMegaminx;:eCounterCW. 1); 
DoLUtK leftFace. rightFace): 

DoLUU[leftFace. rightFace): 

fMega, Slice (kSouthFoleFatie, CMegaminx::eCW, 1); 


//pragma mark = Verification Routines 
iiiiiiiiiiiiiiiimii/iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiWiii 
if Verification Routines 

iiiifliiifl!!if!!liiiiiliiilliii!lli!liliitii!ili!tltt!lifiifmwili 

if see online code archive 

CMegaminxA pp.cpp 

// see online axle archive 

CMegamimccpp 

//include "CMegaminx.h" 

//include ,r CMegarninxApp.h" 

//include <cassert> 

fiil!lil!f!il!!(!liil!!!flll!iili!fli!lflllftiiffmffiimiUiU 

U initialisation of tables 

const CMegaminx:: vertex_t CMegaminx:: kFaceVertices [13] [5] = 

// dummv Rice for 0 

10. Q r 0, 0—(Hr 

// North Pole face 

10. 1. 2 , 3. 4h 


// Northern Equatorial faces 

13. 2, 7 , 12. 8}. 


[2, 1 T 6, 11, 7). 

*1. 0. 5, 10. 61. 

[0. 4, 9. 14. 51, 

14. 3. 8, 13. 9f. 


// South Pole face 

(19. IS. 17, 16. 151. 

// Southern Equatorial feces 

(19. 15. 10, 5. 141. 

(18. 19. 14, 9. 131, 

(17, 18. 13, B, 12] . 

(16, 17, 12, 7, 111, 

(15, 16. 11, 6. 10] 


const CMegaminx;:face_t CHegamlxot: rkCornerFaces [20] [3] - 

If North Pole 

Ii, 5, 41, 

II* 4, 3J, 

II* 3, 21. 

II, 2, 61, 

11. 6. 51, 

// Northern Equatorial 
(4, 5, 01. 

13, 4, 12], 

12, 3, 111, 

12, 10. 61, 

15. 6. 9L 

// Southern Equatorial 

(4, 0, 121, 

(3, 12, 111. 

12, 11. 101. 

16. 10, 91, 

(5, 9. 81, 

// South Pole 

17. 12, 81, 

(7, 11, 12], 

17. 10. HI. 

(7, 9. 101. 

17, 0, 9J 


// list of adjacent face numbers, indexed by face number. 

// each item lists the feces adjacent to this one. 

// in counterclockwise order as viewed from above this Face, 

//This 1st must be coordinated with the vertex lest so that 
// facel 11 touches vertices [0] and | J|. 

const CMegaminx::faee_t CMegaminx:; kAd jacentFaces .[13] [5 ] = 

f 

10. 0, 0, 0. 01, //dummy for face 0 


(4, 

3. 

2. 

6. 

51. 

tl. 

3. 

11. 

10 

. 61, 

U. 

4. 

12, 

11 

. 21. 

11. 

5. 

3. 

12. 

3), 

(1. 

6. 

9, 

S, 

41, 

11. 

2. 

ID, 

9, 

51. 

19. 

10. 

11 

. 12. 81. 

(7, 

12. 

4. 

5. 

9h 

17, 

8. 

5, 

6, 

101, 

(7, 

9, 

6. 

2, 

111. 

17, 

10. 

2, 

3, 

121. 

17, 

11. 

3. 

4, 

0! 


1: 


const CMegaminx: :face_t CMegaminx; :kFaceBelow[20] - 
15, 4, 3. 2, 6. B. 12, 11, 10. 9, 0, 12. 11. 10, 9 r 0, 0, 0, 
0 . 01 ; 

const CMegaminx:: face_t CMegaminx: ;kFaceAbove[2G] = 

10. 0, 0, 0. 0. 4. 3. 2, 6. 5, 4. 3, 2. 6. 5, 12, 11, .1A* 9, 

01 ; 

const CMegaminx::face_t CMegaminx:; kFaceDownRigftt [13 ] = 

(0, 0, 10. 11, 12. 0. 9, 0. 0. 0, 0. 0, 01; 

const CMegaminx: :face_t CMegaminx::kFaeePownLeft [13] = 

(0. 0. 11, 12. 8, 9, 10. 0, 0. 0. 0, 0. 0]: 

const CMegaminx::face_t CMegaminx:ikFaceUpRight[13] = 

10. 0. 0. o.* o* o. 0. 0. 4. 5. 6. 2, 3h 
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consx CMegarnitix:: face_t CMegaminx: :kFateUpLeft [13] = 

(0. 0. 0, 0* 0, 0. 0. 0.. 5, 6, 2. 3 , 4); 

// list of North Pole edges 
const CMegaminx:;face_t 

CMegaminx:: kNorthPo 1eEdgeM [kNumNorthPol eEdges ] = 

U. i. i, x, lit 

const CMegaminx; :face_t 

CMegaminx;; kNo tthPoleEdgeS [kHmnNorthPoleSdges 3 = 

12, 3, 4. 5. 61; 

// list of North Equator edges, 
const CMegaminx::face_t 

CMegaminx; skNorthEqEdgeLtkNumNorthEqEdges] = 

12. 3, 4 1 5. 61; 

const CMegaminx: :face_t 

CMegaminx:tkNorthEqEdgeRlkNumNorthEqEdges] ■ 

16. 2. 3, 4. 51; 

// list of middle equatorial edges. Ordered in two arrays, 

// the first giving the south face and the second the corresponds^ 

// north face. For even indices the edge is below and right of the 
// north face, for odd indices it is below and to the left. 

const CMe ga minx::fac e_t 

CMegaminx:IkMi ddleEqEdgeN [kNumMidd1eEqEdges] = 

15* 4. 4. 3, 3, 2, 2, 6, 6, 51; 

const CMegaminx::face_t 

CMegaminx::kMiddleEqEdgeS[kNumMiddleEqEdges] = 

18, fi, 12, I!, 11, 11, 10. 10. 9.91; 

// list of Southern Equator edges 

const CMegaminx;;:face_t 

CMegaminx;:kSDUthEqEdgel[kNumSouthEqEdges] * 

IS, 9, 10, 11. 121; 

const CMegaminx::face_t 

CMegaminx; : kSouthEqEdgeR [kNumSouthEqEdges j = 

life 8. 9. 10. Ill; 

// list of South Pole edges 

const CMegaminxface_t 

CMegaminx: ikSouthPoleEdgeNlkNuniSouthFoleEdges] = 

(8, 9, 10. 11, 12]; 

const CMegaminx::face_t 

CMegaminx:;kSouthPoleEdgeS]kNumSouthPoleEdges] = 

(7. 7, 7, 7. l\i 


CMegaminx::CMegaminx(const string^ testNumberString) 

// dear all faedets 

std:;merasetCfEdgeFacelets, 0, sizeof(fEdgeFacelets)); 
std::memset(fCornerFacelets. 0. sizeof(fCornetFacelets)); 

// open correct rotations fde 

string rotationsName = string!"rotations") + 
testNumberStting + "txt"; 
fRotationsStream. open (rotatlemsNaitie. c_str ()); 
if (1fRotationsStream,is_open()) 

CMegaminxApp::SayFileError (rotationsName); 
return; 

I 

1 

CMegaminx::~CMegaminx() 

I 

fRotationsStream.closeC); 

) 

void CMegaminx::LoadCornerFacelet(face_t faceNumberi, face_t 
faceNumber2, 

faee_t faceNumberi, color t colorNumber) 

I 

assert[1 <= faceNumberi && faceNumberi <= 12); 

assert[1 <= faceNumber2 && faceNumber2 <= 12); 

assert(l <- faceNumber3 64 faceNumberi <= 12); 

if (faceNumber2 < faceNumberi) 

fCornerFacelets[faceNumberi] [faceNuraber2] [faceNumberi] 

= colorNumber; 

else 

fCornerFacelets[faceNumberi] [faceNumberi] [faceNumber2] 

= colorNumber; 


J 


void CMegaminx::LoadEdgeFacelet[face_t faceNumberi. face_t 
faceNumber2, 

color_t colorNumber) 

{ 

assert Cl < = faceNumberi 66 faceNumberi 12); 
assert(1 <= faceNumberi 66 faceNumberi <= 12); 

fEdgeFacelets[faceNumberi][faceNumberi] = colorNumber: 


void CMegaminx::Slicelrap(CMegaminx;;face_t faceNumbet, 
Direction direction) 

I 

short *pFaceietColorsl[5] . ‘pFaeeietColorsl[5] , 

‘pFaceletColors 3[5] ; // primers Eo colors to move, listed 

(XW 

int it 

// rotate the edge facelets 

for (i =0; i < 5; i++] 

I 

int adj = kAdjacentFaces[faceNumber][i]; 
pFaceletColors 1[i] - 
kfEdgeFacelets[adj][faceNumbet]; 

// adjacent fat e 
pFaceletColorsl [i] = 

6fEdgeFaceiets [faceNumbet] [adj] ; 

// this fate 

I 

RotateFacelers(pFaceletColorsi, direction]; 

RotateFacelets(pFaceletColors2. direction): 

// rotate the corner faedets 

for (i - 0; i < 5; i++) 

I 

int adj Right - 

kAdiacentFaeestfaceNumber][(i “ 0) 7 4 : i - 

U ; 

int adjLeft - kAdjacentFaces[faceNumbet] [i] ; 
int low. high: 

low - CadjRight i adjLeft) ? adjRight : adjLeft; 
high = (adjRlght > adjLeft) 7 adjRight : adjLeft: 
pFaceletColorsI[i] = 

kfCornerFacelers[faceNumber] [low] [high] ;//this face 

low = (faceNumbet < adjLeft) 7 faceNumber : adjLeft: 
high * (faceNumbet > adjLeft) ? faceNumbet ; 

adjLeft: 

pFaceletColorsl[i] = 

6fCornerFacelets [adjRlght] [low] [high] ; //right 
face 

low = (faceNumbet < adjRight) ? faceNumber ; 

adjRight; 

high - (faceNumber > adjRight) 7 faceNumber : 

adjRight; 

pFaceletColorsi[i] - 

&f Corner Facelets [ad j Left] [low] [high]; //leftfacc 

RQtateFaceletsfpFaceletColorsl. direction); 
RotateFaceletfiCpFaceletCoiorsl. direction]; 

RotateFacelets(pFaceletColorsX, direction); 

// write out this rotation to the file 

fRotationsStream << faceNumber << 11 . ” : 
fRotationsStream << ((direction = eCW) 3 ' + 1 : '-'j; 
fRotationsStream << std;:endl; 

) 

void CMegaminx;:Slice(face_t faceNumber. Direction direction. 


assert(clicks >= 0); 
for (int i = Q; i < clicks; i++) 
Slicelmp(faceNumber, direction); 

J 

bool CMegaminx:;Is SoIved() 

1 

bool bSolved = true; 
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for tint 1=1: i <= 12; i++) 

{ 

int rightColor 11 CorrectColor(i); 


// cheek edges 

bSolved = bSolved &«. EfEdgeFacelets[i] [j] — 0 || 
fEdgeFaceletsli] [j]= rightColor): 

// check comers 

for {int k - j + 1; k <= 12; k++) 
t 

bSolved ~ bSolved && (fCornerFacelets [i] [j] [k] = 0 
fCornerFacelets[i][j] [k] = rightColor); 

I 

} 

I 

return bSolved: 


void CMegarainx;:KotateFacelets(short "ppColor, Direction 
direction) 

I 

// rotate a list of 5 facciet colors 
// die pList is an array of 5 pointer to the color entries 
// in either fEdgeFacelets or fComerFacdets, in counterclockwise 
U order. For CCW direction we shift the array right, and 
H for CW direction we shift it left, 
short saveColor - D: 
int i; 

if (direction — eCounterCV) 

t 

// shift right 

saveColor = **(ppColor + 4): 
for (1 * 3: i >= D; i - -) 

* * CppColor + 1 + 1) - “(ppColor + i); 
**{ppColor + 0) = saveColor; 

1 

else 

( 

//shift left 


saveColor = **(ppColor + 0); 
for Cl = 0: 1 < 4; i++J 

**(ppColor + i) = * i (ppColot +1+1); 
**{ppColor + 4) ” saveColor: 

I 

) 

bool CMegaminx:: IsCartierCorrectlyPlaced (vertex_t vertex} 

( 

// get the actual colors and the correct colors; 

// tile item is correctly placed if these lists are 
// rotations of each other. 

int fO, fl* f2; 
int actualColors[5]; 
int correctColors[3] ; 

fO - kCornerFaces[vertex][Oj t 
fl = kCornerFaces[vertex][l]; 
f2 = kCotiierFaces [vertex] [2]; 
actualColors [0] = actual Colors. [3.] = 

CornerFaceletColor(fO* fl, f2); 
actualColors [l] = actualColors[4] - 

CornerFaceleiColor[fl, f2, fO); 
actualColors[2] = CornerFaceletColor( f2, fO, fl); 
correctColors [0] = kCornerFaces[vertex] [0] ; 
correctColors[1] = kCornerFaces[vertex] [lj; 
correctColors [2] - kCornerFaces [vertex] [2l; 
if {correctColors[0] > 6) 
correctColors[0] -= 6: 
if (correctColorsUl ) 6) 
correctColors[1] -- 6; 
if (correctColors[2] > 6) 
correctColors(2] -- 6; 

bool bHaveMatch = false; 

for (int 1 = 0; (i < 3) && IbHaveMatch; i++) 

I 

bHaveWatch = true; 

for (int j = 0; i< 3: j++) 

\ 

if (actualColors[i+ j] correctColors[j]) 
bBaveMatch = false; 
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I 

1 

return bHaveMatch: 

I 

bool CMegaminx::laCornerCorrect(vertex_t vertex) 

( 

int fO = kCornerFaces[vertex][0] ; 
int fl = kCornerFaces [vertex] [1] : 
int f2 = kCornerFaces[vertex][2] : 

bool bOK - 

CornerFaceletColor(fO. f 1. f2) =* CorrectColor(fO) 
U 

CornerFaceletColorCfI* F2. fO) “ CorrectColor(fI) 
H 

CornerFa.celetColor(f2* fD, fl) = CorrectColor(f2) 
return bOK: 

! 

CMegamtrix; ; vertex_t 

CMegaminx: :FacesToVertex(CMegaminx: ::fate_t f0 t 
CMegarninx::face_t Fl ( CMegatninx; ;face_t f2) 
t 

// find the lowest face number, then search the table of comer faces 
if for a match. It is an error if we don't find a match 

int holdFace = 0; 

if {fl < fO) 

\ 

holdFace = fO; 
fO = fl: 
fl = holdFace; 

if Cf2 < fO) 

I 

holdFace - fO; 

fO = fl; 

f2 “ holdFace; 

I 

for tint 1=0: i < 20; i++) 

I 

if (fO — kCornerFacee[i][0]) 

1 

Int trialFacel * kCornerFaces[i] 11 ] ; 
lot trialFace2 ■= kCornerFaces[i]UJ : 

If ( {fl — trialFacel U fl = trialFace2) || 
ffl “ trialFace2 && f2 = trialFacel)) 
t 

return 1; 


] 

} 


// trouble, did not find a match 

;:SysBeep{!) : 
assert(false): 
return 0; 


CMegaminx:;vertex_t 

CMegaminx::CorrectsouthernVertex(CMegaminx::vertex_t vertex) 
t 

// find where vl should be; 

U first read out its current colors, then 
// figure its correct faces 

int oIdf0 1 oldf 1 * o 1 d f2; // old face numbers 

int c0. cli c2; // corresponding current colors 

int nevf Q, newf 1, newf 2 ; // new face numbers 

oldfD = kCornerFaces[vertex][0]; 

oldfl = kCornerFaces[vertex] [1]; 

oldf2 = kCornerFaces[vertex][2]; 

cO - CornerFaceletColor(oldfQ, oldfl. oldf2): 

cl ® CornerFaceletColor(oldf1 * oldf2. oldfO); 

c2 » CornerFaceletColor( qldf2, oldfO. oldfl): 

// in general we can find the face numbers by adding 6 
// to each color, however for Southern Equatorial 
ff vertices there is one color that shoidd mi have 6 
// added, and that is the "noncontiguous* color 

newfO - cQ + 6; 

newfl ■ el + 6; 

nevf2 - c2 + 6: 

if (c0 1= 1 && cl 1- 1 U c.2 !“ 1) 

I 

// not pule, so correct one face 
if (std::aba [nevifG - newfl) — l |] 
atd:labsCnewfO - newfl) = 4) 
newf 2 6; 

else if (atd;;abs(newfl newf2) “ 1 || 

atd::abs(newfl nevf2) = 4) 

newfO -= 6; 
else 

newfl - = 6; 

1 

return FacesToVertexCnewfO, newfl. nevf2); 


CMegaminxi:vertex_t 

CMegaminx::CornerHavingColore(CMegaminx::color_t c0» 

CMegaminx: :color„t cl T CMegaminx:;color_t c2) 
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{ 

int desirsdColors [5] : 

desiredColors [0] = desiredColors[3] “ cG; 
desiredColors [I] = desiredColors [4] ■ cl; 
desiredColors [2] = c2; 
int trialVertex; 

for (trialVertex = 0: trialVertex < 20; trialVertex++) 
I 

// get the actual colors and the correct colors; 

// the item is correctly placed if these lists are 
// rotations of each other, 
int fO, fl. £2; 

£0 - kCornerFaces[trialVertex] [0] : 
fl = kCornerFaces[trialVertex][1]; 
f2 = kCornerFaces[trialVertex] [2]: 
int trialColors [3] ; 

trialColors[0] = CornerFaceletColor(fG* £1* £2}; 
trialColors[1] = CornerFaceletColor(£K f2 p f0); 
trialColors[2] ~ CornerFaceletColor(f2 * f0, fl); 

bool bHaveMatch = false: 

for (int 1 - 0; (i < 3) U IbHaveHatch; i++) 

I 

bHaveMatch = true: 


if (desiredColors[i+ j] 1= trialColors [j]) 
bHaveMatch = false: 

I 

I 

if [bHaveMatch) 
break; 

) 

return trialVertex; 

I 

CMegaminx::vertex„t 

CMegaminx::NextConnterCWVertex(CMegaminx:;face_t faceNumber t 
CMegaminx: :vertex_t vertexMumber} 

I 

for (int i = 0; i < 5: I++) 

I 

if (kFaeeVertices[faceNumber] 111 = vertexNumber) 
return kFaeeVertices[faceNumber] [(i = 4) ? 0 : i + 

1 ]; 

1 

: :SysBeep (1); // trouble, vertex not on face 
assert(false) : 
return -1; 


CMegaininx r:vertex_t CMegaminx; : NextCWVertex (CMegaminx; ;face_t 
faceNumber, 

CMegaininx ;: face_t vertexNumber) 

I 

for (int i * 0; i < 5: i++) 

( 

if [kFaceVertices[faceNumberj [ij = vertexNumber) 
return kFaceVertices[faceNumber][(i -= 0) ? 4 : 1 * 

lh 

1 

:: SysBeep f I); // trouble, vertex not on face 
assert(false); 
return -1: 


void CMegaininx: :FindNonAdJacentSouthFaces[CMegaininx: : vertex,, t 
Vlt 

CMegaminx::vertex_t v2. 

CMegaminx::face_t *pfl. CMegaminx;;face_t *pf2) 

int Fl J2], f 2 [2] ; // candidate faces 

fl[0] = kCornerFaces[vl] [1] ; 
fl [l] *■ kCornerFaces [vl] [2]; 
f2[Oj = kCornerFaces[v2] [1]; 
f2[11 = kCornerFaces[v2][2]: 


for (int i = 0; i < 2; i++) 

I 

for (int j =0; j < 2; j++) 

int dist = f1[±] - f2[j]: 
if (dist < 0) 
dist = -dist; 

if (dist = 2 I| dist = 3) 

( 

* P fi - mils 
• P f2 = f2[j]; 
return; 

I 

1 

1 

:: SysBeep (1); // trouble, couldn't find suitable faces 
assert[false): 

I 

#lfndef NDEBUG 

void CMegaminx::WriteComment(const char ^pComment) 

fRotationsStream << 1 << pComment « std:;endl; 

1 

if else 

void CMegaminx::WriteComment (const char */* pt’ommcnt 7) 

I 

// nothing 

) 

#endif 

bool CMegaminx: :EdgeHasColore(CMegaininx: :face_t fD. 
CMegaminx::face_t fl, 

CMegaminx:;color_t cO, CMegaminx::color„t cl) 

int actualcO = fEdgeFacelets[ffl][f1]; 
int acttialcl “ FEdgeFacelets [fl j [fO] : 

bool bMatches = [(actualcO = c0) && (actualcl cl)) | 
[(actualcO = cl) (actualcl = cG)): 

return bMatches; 

I 

#pragma mark “ CTempRotate =*= 

mmimtmmmmtfmmwmmmwmm 

CTempRotate::CTempRotate[CMegaminx& tMega, CMegaminx:;face_t 
faceNumber, 

int clicks* CMegaminx;:Direction direction) : 
fMega(rMega), 
fFaceNumber[faceNumber), 
fClicks(clicks) H 
fDirection(direction) 

( 

assert(fClicks >= 0): 

FMega.WriteCorament ["CTempRotate ctor"); 
fMega* SliceCfFaceNimber, direction. fClicks); 

) 

CTempRotate::-CTempRotate() 

I 

FMega.WriteComment("CTempRotate dtor"); 
fMega,Slice(fFaceNumber * 

fDirection = CMegaminx::eCW ? 

CMegaminx:reCotmterCW : CMegaminx:;eCV. 
fClicks); 


CMegaminxApp.h 

// see online code archive 

CMegaminx.h 

iiiiiiiiiiininimiiiiiiiimiiiiiiiiiiiiwiiuiiitiititiiMttui 

// 

//The CMegaminx class holds ihe slate of the MegHminx/llicrc's only 
// one operation for changing stale, the Slice function,This class 
U also liandles writing out the rotations files; this placement is 
// somewhat arbitrary, but is useful because it ensures that changing 
// the Megaminx stale will always cause the correct movements to be 
// written out. 

// 
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ffffffffifffffffffffffffffffffffffffffffffffffffffffffftffffffffffffff 

//pragma once 

//include <fstreani> 

//include (string) 
using std:;string; 

class CMegaminx 
[ 

public: 

lititiiitfiiiiittHiiiiiiiiifiiiiiittiUittftiitfitttmttiiitiii 

ff various types and tables describing the Megaminx 

// enum for rotation direction; always measured looking 
fi down on a face, 

if We also use this for an orientation of a corner if 
// die color number increase CCW we call it CCW and if 
// they increase CW we call it CW 
enum Direction 
I 

eCounterCW = 1* 
eCW - 2 

] ; 

// typedefs for face number, color number, vertex number 

typedef int face_t; 
typedef int color_t; 
typedef int vertex_t; 

if vertices are numbered 0-19; these equates give the ranges 
static const int kNumVertices - 20: 
static const vertex_t feFiratNorthPoleVertex = 0; 
static const vertex_t kLastPJorthPoleVertex - 4; 
static const vertex_t kFirstNorthEqVertex " 5; 
static const vertex_l kLastNorthEqVertex = 9: 
static const vertex_t kFirstSouthEqVertex - 10; 
static const vertex_t XLastSouthEqVertex =14; 
static const vertex_t kFirstSouthPoleVertex = 15 
static const vertex_t kLastSouthPoleVettex = 19; 

if vertex numbers of each face, indexed 0 through 19. 
if counterclockwise looking at the face from outside 

static const vertex.,! kFaceVertices[13] [5]; 

// list of all vertices and the adjoining faces. Faces are listed 
// in CCW order started with the lowest-numbered, 
static const facej kGime rfaces [20] [31; 

// list of adjacent face numbers, indexed by face n urn her. 

// each item lists the faces adjacent to this one, 

ff in counterclockwise order as viewed from above lIils face 

//This list must be coordinated witli the vertex List so that 


ff facet 1] touches vertices [0] and [1], 

static const face_t kAdjaeentFaces[13].[5]; 

// list of faces below or below left of a vertex, indexed 
if by vertex number. For North Equatorial vertices the face is 
U bdow (the vertex is its top vertex) and for North Pole 
// and South Equatorial vertices the fact is below and 
ff to the left (the vertix is its upj>er right vertex), 
static const face_t kFaceBelow[20] ; 

// lisi of faces above or above right of a vertex, indexed 
ff by vertex number. For South Equatorial vertices the face is 
// above (the vertex is its bottom vertex) and for South Pole 
ff and North Equatorial vertices the face is above and 
ff to die right (the vertix is its lower left vertex), 
static const face_t kFaceAbove[20]; 

ff for equatorial faces, the faces above and bdow them. 

ff 

ff faces below and to left or right of given North Equatorial 

ff face; indexed by lace number 

static const face_t kFaceEownRight[13]; 

static const face_t kFaceDovnLeft[13]; 

ff faces above and to left or right of given South Equatorial 

ff face; indexed by face number 

static const face_t kFaceUpRigbt[13]; 

static const face_t kFacellpLeft [13]; 

ff list of North Pole edges 

static const int kNumNorthPoleEdges = 5: 

static const face_t kNorthFaleEdgeN[kNumNorthPoleEdges] ; 

static const face_t ktlorthPoleEdgeS[kNumNocthPoleEdges] : 

ff list of North Equator edges. 

Static const face_t kNumNorthEqEdges = 5; 

static const £ace_t kNorthEqEdgeL [kNuiisNartliEq Edges! ; 

static const face_t kNorth&qEdgeR [kNumNorthEqEdgesj; 

ff list of middle equatorial edges. Ordered in two arrays, 

ff the first giving the north face and the second the corresponding 

}f south face. For even indices the edge is be low' and right of the 

// north face, for odd indices it is below and to die left. 

static const int kNumMiddleEqEdges = 10; 

static const face^t kMiddleEqEdgcN[kNumMiddleEqEdgesJ; 

static const face_t kMiddleEqEdgeS[kNumMiddleEqEdges]; 

ff list of Southern Equator edges 

static const int kNuraSouthEqEdges — 5; 

static const face_t kSouthEqEdgeL[kHumSouthEqEdges] : 

static const face_t kSouthEqEdgeR[kUuinSouthEqEdges]; 

// list of South Pole edges 

static const int kNutoSouthPoleEdges - 5: 
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static const face_t kStouthFoleEdgeN [kNumSouthFoleEdgee] ; 
static const face_t kSouthPoleEdgeS [kNumSouthPoleEdges] ; 


Httiiiiiiiiittiiittttiiiiiiuiiiiiiiiiiiumuiiffittmmim 
if public functions 

CMegaminx(const string^ testNumberStrlng); 
"■CMegatainx () ; 


// load a corner facdet; 

ff faceNumber 1 is the face it is on (numbered 1„12> t 
ff faceNumber! and faceNumbei3 arc neighboring frees, 

// and colorN umber is the fredet's color (numbered 1,6), 
void LoadCornerFacelet (f ace_t faceNumberl., face_t 
fsceNumber2. 

face_t faceNumber3, color_t colorNuinberj : 

ff similarly, load an edge fecelet (no face 3 for these) 
void LoadEdgeFacelet(face_t faceNumberl* face_t 
faceNumber2 * 

color_t colorNumber); 

// slice operation; rotate face one click in given direction; 
ff changes our internal state and writes a line to 
// the rotations file. 

//Tliis is a public function so that our helper classes 
H can get to It, 

void Slice(face_t faceNumber, Direction direction, int 
clicks) ; 

if check that the Mcgaminx is correctly solved 

bool IsSalved(): 

ff check whether a corner is correctly placed, based 
ff on its colors.The first checks only placement, not 
ff orientation. 

bool IsCornerCorrectiyPlaced[vertex L vertex); 
bool IsCornerCorrect(vertex_t vertex); 

ff check whether an edge is correctly placed and positioned 

bool IaEdgeCorrect(face_t facek. face.t FaceR) 

( return (fEdgeFacelets[faceL] [faceR] == 

CorrectColor(faceL) 

fEdgoFacelets[faceR][faceL| = 

CorrectColor[faceR)); [; 


ff look up the vertex having these laces 

vettex_t FacesToVertex(face_t fO, face_t fl, face_t f2); 

ff find correct location of the colors at a vertex, 
ff assuming they should l>e in the Southern 
if hull. Returns the correct vertex number. 

//We assume the colors actually belong in I he 
if specified Southern half, so caller 
// must check this. "Southern'* means South Pole 
if or South Equatorial, 

// (Corners with same colors have opposite orientations 
// in the Northern and Southern halves, 

vertex_t CorrectSouthernVertex(vertex_t vertex); 

// find the comer having these colors in this order 
//(with rotations allowed).This means the corner that 
ff is currently colored with these corners, 

color_t CornerllavingColors Ccolor_t cO, eolor_t cl h color T; 
c2); 

// return faedet color of face fl) that borders fl and f2 

color_t CornerFaceletColor{face_t fO, face_t fl* face_t f 2.) 
f if [fl (. f2) return fCornerFacelets [f0] [f 1 ] [ f2] ; 
else return fCornerFacelets[fO][f2] [f1 ] ; 1 : 

// return color of edge on fO that borders fl 

color_t EdgeFaceletColor(face_t fO. face_t fl) 

I return fEdgeFacelets [f0] [f1]; h 

if return correct color of solved Megaminx face 

static color_t CorrectColor [facej: faceNumber) 

1 return (faceNumber <= 6) ? faceNumber ; faceNumber - 

'fish 


// find next vertex on a face 

static vertex_t NextCounterCWVertex(Face_t faceNumber, 
vertex_t vertexNumber): 

static vertex t NextCWVertex[face_t faceNumber, vertex_t 
vertexNumber); 

// find next or previous (numerically) South Equatorial faces 

static face_t NextSoutbEqFace(face_t faceNumber) 

I return (faceNumber = 12) ? 3 ; faceNumber + 1; ]; 

static face_t PrevSouthEqFace(face_t faceNumber} 

I return (faceNumber = 8) ? 12 ; faceNumber - 1; ): 

if find next or previous (numerically) North Equatorial faces 

static face_t NextNorthEqFace(face_t faceNumber) 

I return [faceNumber — 6) ? 2 : faceNumber 31; |; 

static f’ace_t PrevNorthEqFace(face_t faceNumber) 

1 return (faceNumber = 2) ? 6 : faceNumber - 1; |; 

ff tell which region a vertex Is in 

static bool IsNorthPoleVertex(vertex_t vertexNumber) 

[ return [vertexNumber <= 4);) ; 
static boo) IsNorthEquatorVertex(vertex„t vertexNumber) 

( return [vertexNumber ) 4 && vertexNumber v- 9);f: 
Static bool IsSouthEquatorVertex(vertex_t vertexNumber) 

I return (vertexNumber > 9 vertexNumber <= 14);); 
static bool IsSouthPoleVertex(vertex_t vertexNumber) 

I return (vertexNumber ) 14);); 

ff tuO which region a face is in 

static bool IsNotthPoleFace(face_t faceNumber) 

\ return (faceNumber = 1); h 
static bool TsNorthE|itiatorFace(fare i faceNumber) 

I return (faceNumber > 1 lik faceNumber <= S); \; 
static bool IsFouthEquatorFace(face_t faceNumber) 

I return {t'accNimibci > $ && iaceNumber (=11); ]; 
static bool Is5outhPoleFace(face„t faceNumber) 

I return (faceNumber “ 12); 1; 

// find non-adjaeent South Equatorial faces holding 
// these vertices. This is useful for lofting lurau.se 
if we can rotate these two faces Independently without 
// affected the other face's vertex. 

//The vertices \ I and v2 can be on the South Equator, 

// the South Pole, or a mixture; except that they cannot 
ff he on the same vertical line (because they touch the 
ff same faces then); the caller must detect this and not 
// call this routine in this erase. 

static void FindNonAdjacentSouthFaces(vertex.t vl* 
vertex L v2* fate_t *pfl, face_t *pf2); 

// write a comment line to die rotations file telling 

// what we are doing (debug only) 

void WrlteGomment [const char ‘pComment)t 

// check whedier an edge has the given colors (in either order) 

bool EdgcHasColors(face_t fO, Facv./t fl* color_t cO h 
color_t cl); 


private: 

fffffffifffiffifllfffffifffi/iffffffffiffffffffffififlifififffffi 
ff used in implemenlatiun 

void Slicslmp (face_t faceNumber, Direction direction); 

fi slice fine turn 

// utility for rotating part of a face 

static void RotateFacelets (short “ppCoior, 

Direction direction); 


fiifiiiffiiiifiiiffiiifffiiiiffiiifiiiffiififiiiiffiiifiiiiiiffii 

fi member variables 

U colors for edge and comer face lets 

ff colors are numbered l through 6; we use (1 for an invalid entry, 
ff 

ff indices are the lace number (and so run from I through 3 2), 
ff edge ktcckts are indexed hv the two faces they touch, with 
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// the first index being the face they are on, 

// comer facdets are indexed by the three faces they touch, 

// with the first index being the face they are on, 

// with second index < third index. 

V 

//We allocate many more items than are actually valid. 

short fEdgeFacelets [13](13]; 
short fCornerFaceiets [13] [13] [13] : 

// output stream for the answer 

std::ofstream fRotationsStream; 

1 ; 

// class to temporarily rotate a face; when destructed, 

// it rotates back in the other direction,The clicks 
// can he 0, meaning no rotation. 

class GTempRotate 

{ 

public: 

CTempRotate(CMegaminx& rMega, CMegaminx;:fact t faceNumter, 
int clicks, CMegaminx::Direction direction); 

^CTempRotate[); 
private; 

CMegaminx^ fMega; 

CMegaminx; :face_t fFaceNumber; 
int fClicks; 

CMe garninx;:Direction fDirection; 


CSolver.h 

mtmmtmtimmmmiimmmmm 

// 

//This class contains al] the algorithms for solving Megaminx 

// 

////////////////////////////////////////////////////////////////////// 

//pragma once 

//include <fstream> 

//include <string> 
using std;:string; 

//include ,f CMegaminx.h 1 ' 

class CGornerVlsitor; 
class CMegaminx: 

class CSoiver 

\ 

public: 

CSoiver (CMeganiinxS: rMega); 

-CSoiver(): 

// solve the Megamiax and write out the solution 

void Solve[); 

// call visitor 

void VisitAliCornersfCCornerVisitor kaVisltor); 
private: 

fHiiiififtfitfiifiiitiiiiiiiiftlfitiiffififiiiifitifftlitttiffil 

// used in implementation 

// double operations from Meffert 

// RUU = R upper star upper star, and so on 

void DoLQU(CMegaminx::face_t leftFace, 

CMegaminx:;face_t rightFace): 
void DoRUU(CMegaminx::face_c leftFace. 

CMegaminx::face_t rightFace); 
void DoRLL(CMegaminx::face_t leftFace, 

CMegaminx:;face_t tightFaee); 
void DoLLL(CMegaminx;:face_t leftFace, 

CMegaminx::face_t rightFace); 

// distance along either the North or South pole vertices, measured 
// in liit direction of increasing vertex number and w rapping around. 
//We use this when we are going to rotate in this direction. 


//Also: distance along an equator from one face to another 
//This calculates (to - from) mod 5. 

int Distance(int from, int to) 

l int dist - to from: if (dist < 0) dist += 5: return 
dist;}: 

// this checks that the South half edges are an even permutation 
// of the solved position, it returns true if the permutation 
// is even and false if it is odd 

bool CheckEdgeParity(): 

static int ParityLookup{CMegamitix: :colot_t cO, 

CMegaminx;;color_t cl): 

// solution steps 

void Step3(); 
void Step3Edges() ; 

CMegaminx; :face_t Step3_4Drop(CMegaminx: : color_t cQ, 
CMegaminx: realor_t cl); 
void Step3Corners(}; 
void Step4(); 
void Stepi(); 

void Step5PlaceVertex(CMegamlnx;:vertex_T srcVertex, 
int destVertex): 

void StepiOrientVertex(int destVertex]; 
void Step6 0; 

void StepfiP] acePoleEdgefCMegaminx:: face_t fromSFaca, 
CMegaminx;:face_t toEdgeIndex); 
void Step 1 () ; 

void Step7PlaeaPoleEdge(CMegaminx: :face_t srcFac-eN, 
CMegaminx::face_t destFaceL, 

CMegaminx;:face_t destFaceR); 
void Steps(); 

void StepSReferenceEdge(); 
void StepSSecondEdge(); 
void StepSThirdEdgeO : 
void StepSRestoreEquator0 ; 
void StepEOrientFourfive(); 
void Step9(): 

void Step9EquatorAndPole(CMegaminx;:vertex.t dst. 

CMegaminx;:vertex_t sre): 
void SteplOO: 
void Step11{)I 

void Step IIBothEquators[CMegaminx:;vertex_t vCounterCU. 
CMegaminx;:vertex_t vCW): 

// verification steps (these run only in debug mode): 

// they check that various things arc correctly positioned 
// at the end of step n.and assert if they arc not. 

// Each step calls the preceding step, so id I earlier 

// verifications arc a 1 -performed too. 

void Step! Verify() ; 

void StepAVetify{); 

void Step5Ver:i fy 0 ; 

void StepGVerifyO ; 

void Step/Verify{); 

void StepBVerifyO ; 

void Step9Verify [) : 

void SteplOVerify(): 

void SteplIVerify(): 


if member variables 

CM e garni nx h f Me g a; HU ega mi n x being solved 


// CComerVisitor Clasfi 
class CCornerVisitor 
I 

public: 

CCornerVisitor() \ \ \ 
virtual -CCornerVisitor(] 11; 

virtual void VisitCornet(int cornerlndex) = 0; 
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JAVA 

PROGRAMMING 


By Andrew S. Downs 


Dock Tile Imaging 


Changing a Java application’s dock tile 
at runtime 

Overview 

The Dock Manager API allows a programmer to alter the 
tile for an application at runtime. Using the Java Native 
Interface, a Java application can change its tile dynamically 
as well. This involves a combination of Java and native code. 

Two approaches are illustrated in this article. The first 
captures the pixels from a Java image and passes them to a 
native library function, which uses the CoreGraphics (Quartz) 
API to replace the application’s tile (see Figure 1). 



Figure L A modified Dock tile. 

The second example uses QuickDraw to paint a progress 
bar over the tile, as shown in Figure 2. The progress data is 
sent from Java to a native library function, and the imaging 
is done in the library. 




i 


Figure 2. The progress bar at the bottom of the tile , showing 
60% complete . 


If you want to code along with the examples, my 
recommendation is to first download the JNISample project 
from Apple’s developer site (see the URLs at the end of this 
article). Thai project served as the structural basis for the 
code in this article. All the build settings are already in place, 
making it an easy-to-use learning tool. (There are targets for 
compiling both the Java and native code, generating the javah 
file, building a library, etc.) I kept the filenames the same, but 
replaced the content of the various files. In the listings below 
you will see the filenames as they exist in that project. 

Java 

One class (DockTiler) provides most of the functionality 
for this example. It relies on two other classes for getting and 
drawing (offscreen) an image from a local file. You can also 
load an image via a non-local URL, which would allow the 
app to change the tile in response to outside conditions. For 
example, an application that retrieves weather data can 
change the tile to reflect current conditions or the forecast. 

The JNISample class contains main(), the entry point for 
the Java application. It is used simply to instantiate DockTiler 
and invoke one of its instance methods. 

Listing 1: JNISample.java 


J Ml Sample 

Hie classes contained here include: 

JNISample: creates and calls a DockTiler instance. 

DockTiler: loads the image and sends it to the native drawing code. 

LocalFilen allows the user to select a local file for display in llie tile. 
PicmreFrame: an offscreen Canvas which draws the image, allowing DockTiler 
to retrieve the image pixels, 

//The image support comes from the AWT and Lite image package. 

import java.awt.*; 
import java.awt.image.*; 
import java.util.•: 

public class JNISample [ 
public JNISample() 11 

//Test code, 

public static void main (String argali) f 
DockTiler dock = new DockTiler(); 

dock,test(); 

System,out.printIn{ “Finished." ); 

1 

J 


Andrew lias been a Java fan since his first encounter with the language at the WebEdge III conference in 1996. You can reach him at andrew@downs.ws. 
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class BockTiler ( 

// tf we have trouble loading an Image, the values of its width and height will 
if remain at -1. See loadimageo 

int mWidth = -1, mHeight = -1; 

Int mPixels [] ; 

static t 

// Load die Library when diis class gets Loaded. 

System.loadLibrary ( “Example’* ): 


public BoekTiler() [ 


//These are the two functions in the shared library that we will call. 
// Note the declaration as native. 

native void setDockTilet int[] pixels, int width, 
int height } ; 

native void updateProgressBar( int currFercent ) ; 

if The primary test driver. 

public void test() ( 
loadimageO ; 

setBockTilet mPixels, mWidth. mHeight ): 
perfortnTaek() ; 


// Read in the image and retrieve its pixels. 

protected void loadimageO ( 

LocalFile If = new LocalFile£); 

String filename = If. getFilePathO : 

Image image - 

Toolkit.getDefaultToolkit0,getlmage£ filename ): 

// Send the image to the Canvas, where it will he rendered. 

PiCtureFrente pf - new PictureFrame[ image ); 

Frame f w new Frame( ’'Image” ) ; 

// Setup offscreen. 

f.setBounds( -250, 250 t 200. 200 ); 

f.setLayout£ new BorderLayout () ): 
f■add( "Center", pf ); 
pf.setSize£ 128, 128 ): 
f. packf): 

//An invisible window won’t render an image. 

f.setViaibleC true ): 

f. repaint(); 
pf,repaint(); 

// Use the Canvas as the observer during the loading process. 

Int width - image,getWidth( pf ): 
int height * image,getfleightC pf ); 

//Allocate storage for the image data. 

aPixels “ new int[ width * height ]; 

// Create an object to copy the image pixel data into our array. 

PixelGrabber pg - new PixelGrabber( image, 0. 0, 
width, height. mPixels, 0, width ); 

// Copy the pixels to the array. 

try l 

pg.grabPixels (): 

fi Check for error using bit values in the ImageObserver class, 

if ( ( pg.getStatus(J k ImageObserver♦ABORT ) != 0 

return; 

// If successful, set instance attributes to Legitimate values (not -1). 

mWidth = width; 
mHeight = height; 


I 

catch ( InterruptedException e ) L 
return: 

\ 

} 

// For a task that may take some time, it helps to wrap it in a separate method 

// even class, and spin it off as a thread. Here, simply get the current progress 
// and display it, 

protected void performTaskO I 
int percentComplete = 0; 

boolean taskCorapIete “ false; 

while ( JtaskComplete ) I 

// Call the native method that draws the progress bar. 

updateProgressBar( percentComplete ); 

percentComplete * updateTaskO; 

if ( percentComplete >= 100 ) 
taskComplete — true; 

I 


int mCouiit = 0; 

// Lengthy tasks will use a sophisticated approach to determining completion, 
//This example uses a simple loop so we can watch the bar move. 

protected int updateTaskO { 
return mCount++; 

) 


class LocalFile I 

FileDialog mFileDiaiog “ null; 

// Display a dialog asking the user to choose a file. 

public LocalFlleO f 

if ( mFileDiaiog ” null ) [ 

mFileDiaiog = new FileDialog( new Frame0 * 

“Select an image file", FileDialog.LOAD ): 

J 

I 

// Build and return the path to the file (if selected). 

public String getFilePathO [ 
mFileDialog*setVisible( true ); 

String retval = 

if ( mFileDiaiog.getFile£) 1= null kk 
mFileDiaiog.getFiie£).lengthC) > Q ) [ 
retval - mFileDiaiog.getDirectory£): 

if £ Iretval.endsWith£ 

System.getProperty[ "file.separator" ) ) ) 
retval += System.getProperty( "file.separator” ); 

retval += mFileDiaiog.getFilef); 


return retval; 

I 

} 

// A subclass of java.awt.Canvas that draws an Image object. 

class PictureFrame extends Canvas ( 

Image mlmage; 

PictureFrame( Image img ) [ 
super(); 
ml mage = img: 

setBackground( Color,white ); 

1 

public void updatef Graphics g ) \ 
paint( g ): 

1 
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I’d rather create clocks than invoices. 

If I wanted to keep books all day, I’d have been an accountant , 



MYOB software is the simplest, most powerful, most complete 
solution for managing my company on the Mac, from the day to day 
to the bottom line. 

Antique frames. Quartz movements. That f s my business. 

MYOB software works for me. 





// Draw the image, 

public void paint( Graphics g ) ( 
g, drawltnage f mlmage, 0. D, this ) ; 

I 

) 


Java Native Interface Code 

JNI code i s C code that bridges the Java and native worlds, 
handling the conversion between Java data types and their 
native counterparts. The JNIEnv pointer in each function 
indirectly points to a function table containing JNI functions, and 
the jobject references the instance of the class making the call. 
Any additional arguments are the values passed from the java 
code to the native code. 


Listing 2: ExampIeJNILibx' 


Example) NlLib 

The JNI glue tor converting arguments prior to calling through to the native 
code 

//include ”JNISample.h" 

//include Examp leDylib, h" 

JNIBXPORT void JNI CALL Java_DockTiler_setDoekTile ( 

JNIEnv *env r jobject this, jintArray pixels, jint 
width, 

jint height } ( 

// Obtain a pointer to the array to pass to the native function. 

jint *theArray = (*env)■>GetIntArrayElements( 
env, pixels, NULL ): 

if ( the Array t 33 NULL ) \ 

// Call the library function, 

// Note that no adjustments are made to the primitive values. 

setDockTile( theArray. width, height ); 

// Tell the VM we are no longer interested in the array. 

C *env)*)ReleaseIntArrayElements( env. pixels, 
theArray. 

0 ): 

) 

) 

JNIEXPORT void JNICALL Java_DockTiler_updateProgressBarC 
JNIEnv ‘env, jobject this, jint currPercent ) [ 

// Call the library function. 

// No additional translation is needed on primitive values. 
updateFrogtessBar( currPercent }; 

1 


The Library 

The native library contains the actual tile drawing code. 
One function creates an image and replaces the existing tile with 
the new one. The second function uses a completion percentage 
value to determine how much of the progress bar to paint. It 
draws over the bottom of die existing tile. 


Listing 3: ExampleDylib.c 


ExampIeDylib.c 

Perform drawing in the Dock tile. 

i/include <stdio,h> 

//include <Carbcm/Carbon.h> 

//include CApplicationServices/ApplicationServices .h> 


//Args include the array of pixel RGB A values, and the actual image width and 
height, 

extern void setDockTilef int 1 insagePixels. int width, 
int height ) t 

// How many bytes in each pixel? Java uses Tbyte bits 

int kNumComponents = 4; 

GSStatus theError: 

// Several Corel, rap hies variables. 

CGContextRef theContext; 

CGDataProviderRef theProvider: 

CGColorSpaceRef theColorspace; 

CGImageRef thelmage: 

// How many bytes in each row? 

siae_l bytesFerRow “ width * kNumComponents; 

// Obtain graphics context in which to render. 

theContext - BeginCGContextForApplicationBoekTilet); 

if ( theContext 1= NULL ) f 

// Use the pixels passed in as the image source. 
theProvider = CGBataProviderCreateWIthDatal 

NULL, imagePixels, £ bytesPerRow * height ), NULL 


theColorspace = CGColarSpaceCreateDeviceRGB(); 

// Create the image This is similar to creating a PixMap. 

// -The width and height were passed as arguments, 

// The next two values (8 and 32) are the bits per pixel component and 
ff total bits per pixel, respectively. 

If - bytesPerRow was calculated above. 

ff - Use the colorspace ref obtained previously. 

// - The alpha or transparency dma is in the first byte of each pixel 
ff - Use the data source created a few lines above, 

// - The remaining parameters are typical defaults. Consult the API docs for 
ff more Info. 

thelmage = CGImageCreate£ width, height. 8. 32. 
bytesPerRow, theColorspace. kCGIaiageAlphaFi rst. 
theProvider* NULL, 0, kCGRenderinglntentDefault ); 

CGDataProviderRelease( theProvider ); 
CGColorSpaceReleasef theColorspace ); 

ft Set the created image as the tile, 

theError = SetApplicationDockTilelmage £ thelntage ): 
CGContextFlusM theContext ); 

CGIroageReleasef thelmage ]; 

EndCGContextEorAppIicationDockTile( theContext ): 

I 

1 

extern void updateProgressBar{ const int currPercent ) f 
CgrafPtr theFort; 

Rect tbeRect; 
float right = 0; 

ff Ohtain graphics context 

theFort — BeginQDContextForApplicationDockTile(): 

If £ theFort != NULL } I 

ff Good of QuickDraw. 

GetPortBounds£ thePort, ktheRect ); 

// Initially draw the background of the har and frame it, 

if £ currPercent 0 ) ( 

5etRect{ SrtheRect* theRect.left, theRect .bottom 

10 * 

theRect.right. theRect,bottom }; 

ForeColorC redColor ): 

Paint Rect ( fctheRect ); 

ForeColorC blackColot ]; 

FrameRect( ktheRect ): 

1 
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// Calculate right-edge of progress bar. 

if ( ctirrPercent 100 ) 

right: = ( float )theRect * right; 
else 

right = ( ( ( float )theRect.right - 

C float )theRoct.Isft ) / 

( float ) 100 ) * [ float ) currPercent : 

// Draw the entire progress bar up until this point. 

ForeColor( gresnCoior }; 

// Inset the progress rectangle on our own, 

SetRect( SithoRect. theRect. left + 1. 
theRect.bottom - 9. ( int ) right* 
theReet.bottom 1 ) : 

Paint Re'ct( ktheRect ) ; 

QDPlushPortBuffer( thePort. NULL ): 

EndQDContextForApplicationDockTile( thePort J; 

) 

J 

The image creation using the CoreGraphics API is the 
trickiest part. This example uses the fact that a Java int is 4 
bytes, and that alpha (transparency) data, if included, is 
stored in the most significant byte. After some trial and error, 
I found that the settings shown here work for the images 1 
tested against 

Useful URLs 

I used quite a few outside sources (primarily Apple) in 
preparing this article. Though some of these URLs may change, 
l want to at least point you in the right direction. 

* The rile images came royalty-free from The Clip Art 
Connection: 

http://www.dipartconnection.com/photos/index.html ?gid=18937 

* Sun lias a simple PixelGrabber example: 
http://java.sun.com/products/java-media/2D/forDevelopers/ 
2 Dapi/ja va/awt/imag e/Pixe IG ra bbe r. htm 1 

* The QuickDraw API: 

http://devetoper.apple.com/techpubs/macosx/Carbon/graphics/ 

QuickDraw/quickdraw.html 

* The Dock Manager API: 

http://deveioper, apple.com/techpubs/macosx/Carbon/ 
H u ma n I nterf aceToolbox/Dock M a nager/dockman ag er, htm I 

* The CoreGraphics routines are briefly discussed in the 
QuartzPrimer: 

http://developerapple.com/techpubs/macosx/Essentials/QuartzPrimer, pdf 

* A sample JN1 application that formed the basis for the project 
in this article: 

http://developer.apple.com/samplecode/Sannple_Code/Java/ 

JNISample.htm 

* A sample Dock drawing application (in C): 
http://developer.apple.com/samplecode/Sample_Code/ 
Human_lnterface_Too[box/Tiler.htm 

* This one is a book, not a URL, and is very useful: 

Liang, Sheng, The Java Native Interface, Sun Microsystems, 
Inc. 1999. 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Virtuosity 


Programming with QuickTime VR 


Introduction 

QuickTime W (or, more briefly, Q7V7?) is the part of QuickTime 
that allows users to interactively explore and examine photorealistic, 
three-dimensional virtual worlds and objects. A QuickTime VR movie is 
a collection of one or more nodes-, each node is either a panoramic 
node (also known as a panorama) or an object node ( also known as an 
object ), Figure 1 shows a view of a sample panoramic node, and 
Figure 2 shows a view of an object node. (When a QuickTime VR 
movie consists of a single node, folks often refer to it as a panorama 
movie or an object movie, deluding on die type of node it contains.) 



Figure 1: A QuickTime VR panorama 



Figure 2; A QuickTime VR object movie 

QuickTime VR movies are managed by the QuickTime VR movie 
controller, a movie controller component that knows how to interpret 
user actions in a QuickTime VR movie. The QuickTime VR movie 
controller also displays a controller bar with buttons that are appropriate 
to QuickTime VR movies. From left to right, die five buttons allow the 
user to go Ixick to the previous node, out, zoom in, show the 
visible hot spots, and translate an object in the movie window. The 
QuickTime VR movie controller automatically disables any buttons dial 
are not appropriate for the Current node type or movie slate. For 
instance, the back button is disabled in Figure 2 because the movie is a 
single-node movie. Similarly, the translate button is disabled in Figure 1 
because the current node is a panoramic node, not an object node. 

QuickTime has supported QuickTime VR movie creation and 
playback since mid-1995, hi early 1997, Apple released QuickTime VR 
version 2.0, which (in addition to numerous other improvements) 
provided a C programming interface to QuickTime VR, This interface, 
called die QuickTime VR Manager, provides an extensive set of 
functions for controlling QuickTime VR movies. In this article, we’ll take 
a look at the QuickTime VR Manager. 

The QuickTime VR movie controller also allows QuickTime VR 
movies to send and receive wired actions. This allows us, for instance, 
to iLse buttons in a Flash track to control a QTVR movie, as illustrated 
in Figure 3 Here die Flash buttons in the lower-left corner of the movie 
are configured to send die appropriate QuickTime wired actions to pan. 


Tim Monroe in a member of the QuickTime engineering team. You can contact him at monroe@apple.com. The views expressed here are not necessarily 
shared by his employer. 
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REALbasic® 


REAL Software and MacTech present die REALbasic Showcase to 
higlilight some of the fantastic solutions created by REALbasic users 
worldwide.The showcase illustrates die wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific.All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www. real basic, com >. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 




REALBASIC SHOWCASE 



Apple Help Viewer, Microsoft HTML Help, WinHelp..., Why waste 
your precious development time designing and compiling a 
different Help system for each platform when you can easily use 
UniHelp for all of them? 

NO additional piugins or classes needed. Just drag the UniHelp 
module and its graphics folder into your REALbasic project, add 
a few lines of code, create your external help pages, and that's 
it - instant online help for your compiled REALbasic applications 
that looks and functions the same on Classic Mac. Mac OS X 
and Windows 98/NT/M E/2000/XP 



KEY FEATURES: 

• Displays Both HTML and ASCII Text Files. 

• Supports URL Links, Relative Links, Anchors & Email Links. 

• Parses More Than 20 HTML Tags, including <1MG>. 

• Supports Images, Video and Audio. 

• Built-in Search Engine. 

• Hierarchical Listbox Displays Your Help Table of Contents. 

• Customizable Listbox Icons, Window Title, Start Page, Font, 
Contents Sequencing, etc. 

• GUI Support for 6 Languages: English, Spanish, French, Italian. 
Portuguese and German. 

• Small Footprint: Since Your Help Pages are External, only the 
UniHelp Module is Compiled with Your REALbasic Applications. 

• Familiar Help-style Interface with Back, Forward, Home, 

Copy and Print buttons. 

• Easy to Use & Royalty-Free! 

“UniHelp" and "Electric Butterfly" are never mentioned anywhere 
on the UniHelp Interface, providing you with a full-featured generic 
Help solution - your customers will think you built it yourself! 






DOWNLOAD! 

p://w ww.ebutterfly.com 


db Reports 


Printing database driven 
reports from your REALbasic 
project has never beeh easier. 



Powerful expressions with 
easy-to-use interface make 
this an indispensable tool 
the REALbasic 
providing business 


Download a free demo today. 


http://abDataTools.com 


ftp> get pxFTP 


The power and stability of 
the command line... 

The ease of drag and drop! 



pxFTP 


Get it today at... 

PIDOG.COM 


From the maker of... 
jj piDock 
^TelnetLauncher 


% 


piDog Software 
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Picture 

Play 


Create digital image compositions on 
your Mac, quickly and easily. 



For more information, 
email chris@crescendosw.com, or 

visit us today at www.crescendosw.com! 


Corona 

fff' 

accounting software 



"Easy to set up, easy to use, 
and excellent support from 
the developer," 

Five stars on VersionTracker.com 
Four cows on Tucows.com 


• cash entry 
* invoicing 

• payroll 

• reports 


$64.95 


Version 1.9 now with: safes tax accounting 
"keyless entry" invoices 
drag 'n drop accounts 


Free 30 -day trial 

http:// homepage. mac ,co m / id lei v i I d/Coro n a US. hqx 



A best friend for business! 

p.o. box 472 ■ aurora * Oregon • 97002 
id lew i ld@ mac .com 


Extend REALbasic with 


Advanced Plugins 


Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
REALbasic, including multistyled and custom rendering 
spreadsheet controls. 


A 
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C 
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More text 


2 
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Some text 
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4 
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More text 
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More text 
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Some text 

More text 
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More text 

— 
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Some test 

More lexl 

T 
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More than 32k of rows. 
Classic, OS X and Win32. 
Accelerated for maximum 
speed. 

Images in cells. 



Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic, 

Supported Algorithms: 

* Encryption: 

- e-Cry ptlt 

- BlowFish (448 bit) 

-AES (Rijndael) (256 bit) 

* Encoding: 

- e-Cryptlt Flexible 

- Base 64 

- BinHex 


- MacBinary III 

- AppleSingle / Double 

- UUCoding 

■ Compression: 

- Zip on Strings and streams ( gz) 
* Hashing and Checksums: 

- CRC32 / Adler32 
-MD5/HMAC MD5 
-SHA/SHA1 / HMAC SHA1 


Other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 


Format 


« 

Foot 

Size 



'-i Help 



Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 



Einhugur Software 

saies@einhugur.com 

www.einhugur.com 
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iScreensaver 

Designer 

for Macintosh and Windows 



the world's only cross-platform 
screensaver design tool 


* build both Macintosh and Windows screensavers 
with a single dick, on whatever system' you are using/ 

• use arty QuickTime movie format : 

Macromedia Flash, MPEG, Cinepak, MP3, Midi, AVI, DV Video... 

* include a hidden movie that can be unlocked 
with a registration code 

* customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

* screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

editor 

supports 
interactive Flash 
and QuickTime 


consistent 
cross-platform 
user interface 


try before you buy 
fully functional 
online downloads 


http:/ iScreensaver. net 

email: info @ iScreensaver. net 



the iSfcnsGtmsver Designer edtfma enwronmenl 


* supported systems, as of November 2001, include: 

Macintosh OS 8,6 to 9-2, Microsoft Windows 95/9S/ME, NT4/NT2000/XP 


HwJ-i Hein Inc AM Ffttnj HEserved. 

■So csr«ht<r J<:e tub Gpugkftag log* art LrgPiriiiarfci |rr 

Aopls, *lKWntM. ■ r*l ^uoTlmK grp tTOdrmphii- gndfflr crw<maris or Applo- JfimBiHflf, Inc. 

HjcrpmpPia Hath Is a odd *-.*k of Haromscip, |nc. Mi^woii .u ttnidtnn hik mgi*tfrnrt trgppmpr^s pi rkppjMft Carpratiw 
*n rttipr grg propp^iv pf the!* 1 wfrer! Mgpe lsto FEdLbaic. 


Whistle Blower 

Enterprise server monitor and restart utility 

whistleblower*sentman.com 

Connect to and validate the response from web servers, 
cgi scripts and over 23 other types of servers. 

Send email , pages and perform unattended restarts via 
MasterSwitch or Power Key. 

Shifts make sure that the person on call when the server 
goes down is the one who gets the page. 

68k, PPC and Carbon 

Web based administration lets you check on and restart 
your servers from anywhere. 

Customize your response to on outage with Apple Script 

email us at whi5tleblower@sentman.com 




Control up to 12 changers (4,800 music CDs) 
Control Any Brand Stereo Receiver 
Play MP3 and other Sound Files 
Plus much, much more!!! 

www.titletrack.com info@tifletrack.com 
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tilt, or zoom the panorama. (We saw how to attach wired actions to 
Flash track buttons in 'The Flash 0: Revenge of the Trickster", MacTecb, 
February 2002.) 

8 Q )qihi|Tin.iW 





Figure j A Flash track controlling a QuickTime VR movie 

Well take a look at the actions that can be targeted at a QuickTime VR 
movie, and we'U also see how to attach wired actions to dements in a 
QuickTime VR movie. We can attach wired actions to a particular node 
or to a particular hot spot in a node. So, for example, we could wire a 
hot spot to launch the user's web browser and navigate to a particular 
web site when the user clicks that hot spot. Or we can liave some 
actions triggered when the user enters a ncxle. We won’t learn how to 
build QuickTime VR movies in this article, but we will need to 
understand some of the structure of these movies in order to learn how 
to attach wired actions to nodes and hot spots. 

Tiie QuickTime VR Manager 

The QuickTime VR Manager provides a large number of 
capabilities that we can use to customize and extend the user's virtual 
experience of panoramas and objects. Here we'll summarize the basic 
capabilities of the QuickTime VR Manager. Then, in the Mowing 
sections, we’ll illustrate how to use some of them. The QuickTime VR 
Manager provides these main capabilities: 

* Positioning. A QuickTime VR movie file contains a scene, which 
is a collection of one or more nodes. Each node is uniquely 
identified by its node ID, Widiin a panoramic node, the user's view 
is determined by three factors: the pan angle, the tilt angle, and the 
vertical field of view- (sometimes also called the zoom angle). For 
objects, the view is also determined by the view center (the position 
of the center of the object in the movie window). The QuickTime 
VR Manager provides functions to get and set any of these items. 
For instance, we can programmatically spin an object around by 
repeatedly incrementing the current pan angle. 

* Hot spot handling. We can use the QuickTime VR Manager to 
manage any hot spots in a panorama or object. For instance, we can 
trigger a hot .spot programmatically (dial is, simulate a dick on the 
hot spot), enable and disable hot spots, determine whether the 
cursor is over a hot spot, find all visible hot spots, and so forth. We 
can also install a callback routine that is called whenever the cursor 
is over an enabled hot spot, 

* Custom node-entering and -leaving behaviors. The 

QuickTime VR Manager allows us to perform actions whenever 
the user enters a new node or leaves the current node. For 
instance, we might use a node-entering procedure to play a 


sound when the user enters a particular node. Or, we can use a 
node-leaving procedure to prevent the user from leaving a node 
until some task has been accomplished. 

• Getting information. We can use die QuickTime VR Manager to 
gel information about a scene or about a specific node. For 
instance, we might want to determine the ID and type of the 
current node. Much of the information about scenes and nodes is 
stored in atoms in the movie file. To get information about a scene 
or node that isn’t provided directly by die QuickTime VR Manager, 
well need to use the QuickTime atom container functions to 
extract information from those atoms. 

• Intercepting QuickTime VR Manager functions. We can 
intercept calls to some QuickTime VR Manager functions in order 
to augment or modify their behavior. For example, to assign 
behaviors to custom hot spots, we can install an intercept routine 
that is called whenever a hot spot is triggered Our intercept routine 
might check the type of the triggered hot spot and then perform 
die actions appropriate for that type. Another common use of 
intercept routines is to intercept positioning functions (changing 
die pan, tilt, and field of view) and adjust environmental factors 
accordingly. For instance, we can adjust the balance and volume of 
a sound as the pan angle changes in a panorama, thereby making 
it appear that the sound is localized within the panorama, 

• Accessing the prescreen buffer. QuickTime VR maintains an 
offscreen buffer for each panorama, called die prescreen buffer : 
Tlie prescreen buffer contains the image diat is about to be copied 
to die screen We can use QuickTime VR Manager functions to 
access the prescreen buffer, perhaps to draw a graphic image over 
the panorama. 

This list is not exhaustive. The QuickTime VR Manager provides 
many other capabilities as well, For a complete description, see die 
technical documentation cited at the end of this article, 

QuickTime VR Mow; Piayrack 

Our existing sample applications, such as QTShelk are already able 
to open and display QuickTime VR movies. The QuickTime VR movie 
controller handles the basic click-and-diag navigation, keyboard input, 
and controller liar events. We need to use die QuickTime VR Manager 
only if w F e want to exploit some of the capabilities described just above. 

Initializing the QuickTime VR Manager 

Before we can call the QuickTime VR Manager, however, we need 
to do a little setting up (over and above whafs required for using 
QuickTime). First, we need to ensure that die QuickTime VR Manager 
is available in the current operaring environment. There are several 
Gestalt selectors that we can use to see whether the QuickTime VR 
Manager is available and what features it has. Listing 1 show's the 
definition of the QTVRUtilsJsQTVRMgrlnstalled function, which 
indicates whether the QuickTime VR Manager is available in die current 
operating environment, 

Listing 1: Determining whether the QuickTime VR Manager is 

awHIaUe __ 

QTVRUtib_IsQ r TV r RMgrlnstaJl(:d 

Boolean QTVRUtiIs_IsOTVRMgrInstalled (void) 
i 

Boolean myQTVRAvail = false: 
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long myAttrs; 

OSErr myErr = noErr; 

myErr = Gestalt(gestaltQTVRMgrAttr, fi^yAttrs); 
if (tnyErr — noErr) 

if (myAttrs & (1L ^ gestaltQTVRMgrPresent)) 
myQTVRAvail = true: 
return(myQTVRAvai1); 

} 

For simplicity, well introduce a global variable to keep track of whether 

the QuickTime VR Manager is available: 
gQTVRMgrlsPresttit = QTVRUtlls_IsQTVRMgrinstailed(); 

On Windows operating systems, we need to call the 
lnitializeQTYR function to initialize the QuickTime VR Manager, like 
this: 

#if TARGET_QS_WIN32 
InitializeQTVRO ; 

#endif 


We also need to dose our connection to the QuickTime VR Manager 
before our application terminates: 

jfttf TARGET_OS_WIN 32 
TerainateQTVRC); 

Ihn&if 


Calling any otlier QuickTime VR Manager functions before calling 
InitializeQTVR will result in :m error on Windows. 


Getting the QTVR Instance 

The QuickTime VR Manager keeps track of QuickTime VR movies 
using an identifier called a QWR instance (of data type QTVRInstance), 
Virtually all QuickTime VR Manager functions operate on Q'lVR 
instances. You can think of an instance as representing a scene — that 
is t a collection of nodes — or sometimes just die ament node. We 
obtain a QTVR instance by calling the QTVRGetQTVRinstance function. 
QTVKGetQTVRlnstance rakes a reference to a Q'lVR track, which we 
ran obtain by call!fig QTVRGetQTVKTrack, Listing 2 shows our 
definition of QTApp_SetupWindowObject T which we call for every 
movie we open. 


listing 2: Getting a QTVR instance 

QTAppJt'tupWindawOhfea 

void QTApp_SetupWindowObject (WindowQbject thetfindowOhjent) 

I 

Track myQTVRTrack - NULL: 

Movie jnyMovie NULL: 

Mo vie Cent roller myMC * MULL; 

QTVRInstance myInstance = NULL: 

if (theWlndowObjecT = NULL) 
return: 

// make sure we can safely call the QTVR API 

if (IgQTVRHgrlsPresent) 
return: 

// lind (he QTVR track, if there is one 

jnyMC - ( 4 *theWindowQbject),^Controller: 
myMavie = (* •thetfindowOb j ect) , fMovie; 
myQTVRTrack = QTVRGetQTVRTrack(tnyMovie. 1); 
QTVRGetQTVRlnstance[ficmylnstance t myQTVRTrack. myMC}; 
(**thetfindowObject)*flnstance ** raylnstance; 

// do :iny QTVR window configuration 
If (mylnstance != NULL) { 

// set unit to radians 

QTVRSetAngcilarUnits (my Instance. kQTVRRadians); 

1 

J 

Notice dial we keep track of the Q'lVR instance by storing it in the 
(Instance field of the window object associated with die movie (here, 
theWindowObject), This gives us an easy way to determine whether a 


given movie window contains a QuickTime VR movie. Notice also that 
we call the QTVRSetAnguIarUnits function to set our preferred angular 
units to radians. The QuickTime VR Manager can work with either 
degrees or radians when specifying angular measurements (for 
instance, when we call QTVRGetPanAngle). 'Hie default angular unit 
type is degrees, internally, the QuickTime VR Manager always uses 
radians, and in some situations it gives us measurements in radians no 
matter what the current angular unit, in general, therefore, I find it 
easier to work in radians mast of die time, so IVe reset die angular unit 
type to radians. (Your preference may vary,) We can define some 
simple macros to allow us to convert between degrees and radians: 

//define kVRPi ((float)}.1415926535398) 

//define kVR2Pi ((float) ( 2.0 ‘ 3 ,1413926535898)) 

//define QTVRUtils_DegreesToRadians{x) \ 

((float)[(x) * kVRPi / 180,0)) 
//def ine QTVRUtils_RadiansToDegrees (x) \ 

((float)((x) * 180.0 / kVRPi)) 

We don't need to explicitly release or dispose of a QTVR instance; 
die value we obtain by calling QTVRGetQTVRlnstance remains valid 
until we dispose of the associated movie controller. 

Controlling View Angles 

Finally we re ready to use the QuickTime VR Manager to do 
some real work. The most basic way to use the API is to control 
the view angles of a node — the pan, till, and field of view angles. 
Listing 3 defines a function that gradually increments the pan 
angle through 360 degrees, With panoramas, this has the effect of 
making the user seem to spin a full circle (as if the user were 
spinning on a rotating stool), With objects, this has the effect of 
making the object spin around a full circle (as if the object were 
spinning on a turntable), 

Listing 3: Spinning a node around once 

SpinAmundOiict 

void 5pinAroundOnce (QTVRInstance thelnstance) 

[ 

float rayOrigFanAngle. myCiirrfanAngle: 
myQrigPanAngle — QTVRGetPanAngle(thelnstance): 
for (myCurrPanAngle = myGrigPanAngle: 

myCurrFanAngle <“ myOrigPanAngle + kVR2Fi; 
myCurrPanAngle 4-= QTVRUtils_DegreesToRadians [10.0]) l 

QTVRSetPanAhgle(theInstance. myCurrPanAngle): 

QTVRUpdate(thelnstance. kQTVRCurrentMode): 

I 

1 

The idea here is simple: get the starting pan angle (by calling 
QTVRGetPanAngle) and then repeatedly increment die pan angle by a 
certain amount (here, 10 degrees) until a full circle has been traversed. 
Note that we need to call the QTVRUpdate function after we set a new 
pan angle to make sum the updated view is displayed on the screen 

Drawing on a Panorama 

Suppose we want to draw a logo or other graphic element on 
top of a panorama (as seems to be in vogue on broadcast television 
channels these days), As we learned earlier, we can draw into a 
panorama s prescreen buffer before that buffer is copied to the 
screen. (Object nodes don’t have prescreen buffers, so this technique 
won t work for those kinds of nodes.) We exploit this capability by 
installing a prescreen buffer imaging completion procedure t which is 
called by the QuickTime VR Manager each time the prescreen buffer 
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Ls about to be copied to the screen. We install our procedure using 
die QTVRSetPrescreenlmagingCompleteProc function: 

ImaginsCorapleteUPP mylmagingProc; 

mylmagingProc = NewImaglngCornpleteFioc(MyPrescTeenRoutine): 
QTVRSetPrescrefinlmglngCampleteProc (my In stance. 

ntylmagingProc. {Sint32)theWindowObject, Oh 

The QTVRSetPrescreenlmagingCarnpleteProc function takes four 
parameters, which are the QTVR instance, a universal procedure 
pointer to the imaging complete procedure, a four-byte reference 
consLanL, and four-byte flags parameter, Jn this case, we pass the 
window object reference as the third parameter so that the 
imaging complete procedure can access any data associated with 
the window. 

Our prescreen buffer imaging completion procedure is called 
after QuickTime VR has finished draw ing into the prescreen buffer. 
When it’s called, the current graphics port is set to die prescreen 
buffer. All we need to do is draw a picture at the appropriate spot, as 
showai in Listing 4. 

Listing 4: Drawing a pictiire on top of a panorama 

MyPresoeenRouiine 

pascal GSErr MyFrescreenRoutine 

(QTVR In stance thelnstance, WindowObject theWindowOb ject) 

[ 

#pr a gma units ed(theIn s tance) 

AppliestionDataHd 1 myAppData ; 

Rect myHovieRect; 

Rect myPictRect; 

//get the application-specific dau associated with the window 
myAppData = (AppllcatlonDataHdl) 

GetAppDataFrotnWlndowClbject (TheWindowObject) ; 
if [myAppData = NULL) 
return(paramErr); 

// if there is no picture to display just return 
if (("cnyAppData] . fPicture = NULL] 
return(noErr): 

// get tlit: current situ of the movie 

GetMovieBoxf('‘theWindowObject).fMovie. kmyMovieRect): 

// set the si/c and position of the overlay rectangle 
MacSetReetCfonyPictReet, 0, 0, 32, 32); 

MacQff setRect (knyFictRect. 

myHovieRect.*right - (myPietRect.right +5), 
myMovieRect.bottom ■ (myPictRect-bottom + 5)); 

// drnw the picture 

DrawPiciure{[*'myAppData).fPicture, ^myPictRect); 
return(noErr); 


#pragma unused(thelnstance f theWindowObject) 
Boolean myCancelInterceptedFroc = false; 

switch (theMsg-Selector) [ 

case kQTVRTriggerfiotSpotSelector: 
MyPlaySoundO : 
break; 

) 

‘cancel = myCancellnterceptedProc; 


.An intercept routine is executed whenever the intercepted routine 
is called, either programmatically or by a user action. On entry, the 
QuickTime VR Manager provides three pieces of information: the 
relevant QTVR instance, a pointer to an intercept record , and an 
application-defined reference constant, which we use here to pass in 
die window object. The intercept record (pointed to by the theMsg 
parameter) has tliis structure: 


struct QTVRInterceptRecord t 


Sint32 

reserved1; 

Sint32 

selector; 

SInt32 

reserved2; 

SInt32 

reserved3: 

SInt32 

pararaCount; 

void 

'parameter[6] 


For present purposes, we need to inspect only the selector field, which 
contains a value that indicates which intercepted routine Ls being called. 
As you can see in Listing 5, we look for any calls to 
QTVRTriggerHotSpot and call the application-defined function 
My Play Sound when we get one. 

We install an intercept procedure by calling the 

QTVRlnstalllnterceptProc function, as shown in listing 6. 

Listing 6: Installing an Intercept routine 

MylnsCilllniL'irLpiKouLiriL 

void MyInstallInterceptRoutine { 

QTVRInstance thelnstance, WindowObject theWindowObject) 

| 

QTVRlnterceptLTPF mylnterceptProc; 
mylnterceptProc = 

NewQTVRInterceptProc[MyInterceptRontine); 
QTVRlnstalllnterceptFrac (thelnstance. 

kQTVRTriggetHotSpotSelector. mylnterceptProc, 

CSIat3'2) theWindowOb ject, 0): 


There's nothing very complicated in Lliis prescreen buffer imaging 
completion procedure. Essentially, it just figures out where in the buffer 
to draw the picture and ihen draws it. We assume that a handle to the 
picture data Ls stored in die (Picture field of the application data record. 


Intercepting QuickTime VR Manager Functions 

Suppose we want to play a sound every time the user dicks on 
(thai is, triggers) a hot spot, The easiest way to do this is to install an 
intercept procedure that is called each time a hot spot is triggered. The 
intercept procedure simply plays the sound and then returns, 
whereupon QuickTime VR processes the hot spot click as usual. 
Listing 5 shows a simple hot spot triggering intercept procedure 


Listing S' Playing a sound on hot spot dicks 

pascal void MylnterceptRoutine { 


MylntcrccptRouiinc 


QTVRInstance thelnstance, 
QTVRInterceptPtr theMsg, 
WindowObject theWindowObject, 
Boolean 'cancel) 


Tiie QuickTime VR Fee Format 

Unlike movies containing other interactive media types (such 
as sprite or Flash) where the media data can be stored in a single 
track, a QuickTime VR movie always contains several tracks. A 
panorama movie, for instance, contains a panorama image track 
(which holds the image data for the panorama), a panorama track 
(which contains information about the panoramic node), and a 
QTVR track (which maintains general information about the movie, 
such as the default imaging properties). Similarly, an object movie 
contains an object image track ( which holds the image data for the 
object), an object track (which contains information about the 
object node), and a 0717? track. For multi-node movies, the QTVR 
track also contains a list of the nodes in the movie and an indication 
of which node is the default node. Movies with hot spots also 
contain a hot spot image track (a video track where the hot spots 
are designated by colored regions). 

Usually this structure is important to us only when we want to 
create a QuickTime VR movie. But it’s also useful when we want to 
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alter an existing QuickTime VR movie or to extract information not 
provided by die available QuickTime VR Manager functions. 

Working with Node Information 

A QTVK track maintains general information about a QuickTime 
VR movie. Each individual sample in the QTVK track’s media is an 
atom container called a node information atom container This atom 
container holds a node header atom , which contains information 
about a single node, such as the node’s type, ID, and name. The 
node information atom container can also hold a hot spot parent 
atom if the node has any hot spots in it. The QuickTime VR Manager 
provides the QTVRGetNodelnfo function drat we can use to get a 
copy of a particular node information atom container or of any of its 
children. Listing 7 defines a function that we can use to get a copy 
of a node header atom lor a specified ntxle ID. 

Listing 7: Finding the node header atom data 

QTVllL)tiIs_(:ietN(>deHGitltrAl[>fiiDitUi 

0 SE rr GTVRU tils_Get No d eHead e r At omDa ta 

(QTVRInstance thelnstance, UInt32 theNodelD* 

QTVRNodeHeaderAtom?tr theNo deHdrPtr) 

[ 

QTAt omC o n taine r myNod eInfo; 

QTAtom myAtom; 

OSErr myErr = tioErr; 

//get the ntxle information atom container for she specified rnxle 
myErr - GTVRGetti6deInfo(theInstance, theNodelD, 
imyNodelnfo); 
if [myErr != noErr) 
return(myErr); 

// get the single node header atom in ttie node infortnalitm atom container 
myAtom = GTFindChildEylD(myNodeinfo. 

kParentAtomlfiContainer. kQTVRNodeHeaderAtomType, 1, 
NULL); 

if [myAtom 1= 0) 

myErr = QTCopyAtamDataToPtr (myNodelnfo, myAtom, false, 
sizeof(QTVRNodeHeaderAtom), theNodeHdrPtr, NULL); 

else 

myErr - cannotPindAtomErr; 

GTDisposeAtomContainer(myNodelnfo); 
return[myErr); 


As you can see, we call QTVRGetNodelnfo to get the node 
information atom container for the specified node ID; then we call 
QTFindChildBylD to find the single node header atom inside that 
container If we find that atom, we call QTCopyAiomDataToPrr to make 
a copy of its data. A node header atom has this structure: 

struct QTVRNod eHeadsr At did I 


tllntl.fi 

majorVersion; 

Ulnt16 

minorVersion; 

OSType 

nodeType; 

QTAtomID 

nodelD; 

QTAtomlD 

nameAtomlD: 

QTAtomID 

oommentAtoralD; 

Ulnt 3-2 

reserved1; 

UInt32 

reserved2: 


h 

listing 8 defines the function QTVRl'tils_GetNodeType, which 
reads the nodeType field of a node header atom to determine the 
ntxle type. On fact, the QuickTime VR Manager provides the 
QTVRGetNodeType function to get a node's type; we present 
QTVRUtils_GetNodeType simply to show another way of getting 
ihat information.) 


listing 8; Getting a node type 

QTVRL; r ilsGttSkxte Type 

OSErr QTVRUtils_GetWodeType (QTVRInstance thelnstance, 

Hint3-2 theNodelD, OSType *theNodeType) 


QTVENodeHeaderAtom myNodeHeader; 

OSErr myErr “ noErr; 

// make sure we always return some meaningful value 

‘theNodeType = kQTVRUnknownType; 

// go die node header atom data 

myErr = QTVRU111s jGe t Nod ehea de rAt ornDat a(theInst ante. 

theNodelD, SmyNodeHeader); 
if (myErr = noErr) 

*theNodeType = EndianU32_BtoN[myNodeHeader.nodeType); 
return[myErr); 


There is no need to deallocate die block of data returned by 
QTVTlUtils.GetNodeHeaderAtomDaia because it is allocated on the 
stack in a local variable. 


Working with a VR World 

All samples in a QTVR track use a single sample description. Tie 
data field of dial sample description holds a 17? world atom container ; 
which holds general information about the scene contained in die 
QuickTime VR movie, including die name of the entire .scene, the 
default node ID, and the default imaging properties. We can use die 
QTVRGetVRWorld function to retrieve a copy of a movie’s VR world 
atom container listing 9 illustrates how to use this function. 


Listing 9: Finding the VR world atom data 

QTVRl JtitsJXtVWi»k)HeadcrAtumDflta 

OSErr QTVRUtils_GetVRWorldHeaderAtomData 
(QTVRInstance thelnstance, 

QTVRWorld Head erAtomPt r t heVRWor1dHd rA t omPt r) 

( 

QTAtomC o ntaine r my VRW arid; 

QTAtora myAtom: 

OSErr myErr = noErr; 

// gd lilt: VR world 

myErr = QTVRGetVRWorld(theInstance, &rayVRWorld): 
if (myErr 1= noErr) 
return(myErr); 

// get the single VR world header atom in the VR world 
myAtom = QTFindChildByIndex(myVRWorld„ 

kParentAtomIsContainer * kQTVRWorldHeaderAtomlype, 1 * 

NULL); 

if (myAtom jEf* 0) 

myErr = GTCopyAtomDataToPtr(rayVRVarid, myAtom. false, 
sizeof(QTVRWorldHeaderAtoinj t theVRWorldHdrAtomPtr, 
NULL); 

else 

myErr = cannotFindAtomErr; 

QTDisposeAtomContainer(myVRWorld): 
return(myErr); 


A VR world atom container contains (perhaps among other things) a 
single VR tmrld header atom, whose structure is defined by the 
QTVRWorldHeaderAtom data type: 

struct QTVRWbrldHeaderAtora I 


Ulnt16 

majorVersion: 

Ulnt16 

minorVersion; 

QTAtomID 

nameAtomlD: 

Ulnt32 

defaultNodeXD 

UInt32 

vrWorTeLFlags; 

UInt.32 

reserved]: 

Ulnt32 

reserved2: 


1 ; 


We can use this information to determine the ntxle ID of a scene's 
default node, as shown in Listing 10 


Listing 10; Finding a scene's default node 

QTVRl tils_( ielDefaulIN od eID 

UInt32 QTVRUtils_GetDefaultNodelD (QTVRInstance thelnstance) 

1 
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QTVRWorldHeaderAtom myVRWorldHeader : 

UInt32 myNodelD = kQTVRCurrentNode; 

OSErr my Err = noErr; 

myErr = QTVRUtils_GetVRWorldHeaderAtDi]iData (the Instance. 

&myVRWorldHeader): 
if (myErr = noErr) 

myNodelD = EndianU32_BtoN(rayVKWotldHeader,defaultNodeID); 
return(rayNodelD): 

I 

Q1VRUtils_GetDefaultNodelD can be useful if we need to know 
die ID of a movie's default node, since diere Ls no QuickTime VR 
Manager function dial returns tliis information directly. 

Wired Actions and QuickTime VK 

In a handful of recent articles, weVe seen how to work 
with QuickTime wired actions in conjunction w'ith sprite tracks, 
text tracks, and Flash tracks. We use wired actions to atLach 
dynamic, interactive behaviors to elements in a QuickTime 
movie and to allow different elements in those movies (and 
indeed in different movies) to communicate with one another. 
In this section, well investigate how to work with wired actions 
and QuickTime VR movies. 

Sending Actions to QuickTime VR Movies 

let's begin by taking a look at the wired actions that can 
be targeted at a QuickTime VR movie. When action wiring was 
first introduced, in QuickTime 3.. these five wired actions were 
supported: 

emim [ 

kAc t ionQT VRS e t P anArs gl e 
kActionQTVKSetTiItAngle 
kActIonQTVRS et FieIdOfView 
kActionQTVRShowDe faultView 
kActlonQTVRGoToNodeID 
I; 

The first three actions allow us to set a new pan angle, tilt 
angle, or field of view in a QuickTime VR movie. Each of these 
actions takes a single parameter, a value of type float that specifies 
die desired new angle. This value should be specified in degrees 
(not radians) and is by default an absolute angle to pan, tilt, or 
zoom to. It's often useful to specify a relative value instead; we can 
indicate that the parameter value is relative by inserting into the 
action atom an atom of type kActionFlagS whose atom dam is a 
long integer with (at least) the kAct ion F lag Action IsDeJta flag set, 
Listing II show's how r we can build an atom container holding a 
wired atom that pans the target QuickTime VR movie one degree 
to the left each time it gets an idle event, (Well see later how to 
make sure the movie is sent idle events.) 

Listing 11: Panning a QuickTime VR movie during idle events 

AddVRAciJ "nsuddlcActio nG) ntalncr 

static GSErr AddVRAct_CrsateIdIeActioiiCoiitaineT 
(QTAtomContairier ‘theActions) 
i 

QTAtom myEventAtom = 0: 

QTAtom myActionAtom = 0; 

long myAction; 

float myPanAngie = 1.0: 

Ulnt32 myFlags; 

OSErr myErr - noErr; 

myErr = QTNewAtomContainer(theActions); 
if (myErr 1= noErr) 
goto bail: 

myErr = QTInsertChild{*theActions, kFarentAtomIsContainer* 


kQTEventldle, 1, 1, 0, NULL, tanyEventAtom): 
if (myErr != noErr) 
goto ball; 

myErr = QTInfiertChild’(*theActions, myEventAtout. kAction, 

1. 1. 0, NULL, AmyActionAtora): 
if (myErr J= noErr) 
goto bail: 

myAction = EndianS32JtftoB(kActionQTVRSetPanAngle); 
myErr = QTInsertCbild[‘theActions, myActionAtom* 

kVhichAction, I. 1. sizeof(long)* ^myAction, NULL}; 
if (myErr != noErr) 
goto bail; 

AddVEAct_ConvertFlQatToBigEndian{&myPanAngIe); 
myErr = qTInsertChild(‘theActiona* rayActionAtom, 

kActionParameter, 1, 1* sizeof(float)* kmyPanAngle, 
NULL); 

if (myErr 1“ noErr) 
goto bail; 

rayFlags = EndianU32_NtoB(kActionFlagActionIsDelta | 
kAc t i onF 1 a gP a r am.et e rWrap sAround} : 
myErr = QTInsertChild(‘theActions, rayActionAtom, 

kActionFlags, 1, 1, sizeof(UInt32)* firaiyFlags, NULL): 

bail: 

return(myErr); 

) 

The action kActionQTVRShowDefaultView sets the current node 
to its default view' (that is t the view that Ls displayed w hen the nixie Ls 
fast entered). The kAaionQTVPGoToNodelD action takes a single 
parameter that specifies a node ID; w hen the action Ls executed, the 
node with that ID becomes the ament ncxle, QuickTime 3 also 
introduced four wired action operands, which we can use to get 
information about the current state of a QuickTime VR movie: 

emnn [ 

kOperandQTVRPanAngle = 4096. 

kOperandQTVRTiItAngle = 4097. 

kOperandQTVEFieldOfVie’w = 409B. 

kOperandGTVRNodelB = 4099 

): 


QuickTime 5 added three more actions that w r e can send to a 
QuickTime VR movie: 

emm [ 

kActlonQTVREnableEotSpot - 4101. 
kActionQTVRShowHotSpots = 4102, 

kAc tionOfTVET rans lat eOb j ect = 4103 

h 


The kActionQTVREnableHotSpot action enables or disables a hot spot. 
Tills action requires two parameters, a long integer that specifies a hot 
spot ED and a Boolean value that specifies whether to enable (true) or 
dLsable (false) tlie hot spot. The kActionQTVRShowHotSpots action 
shows or hides all hot spots in a node, depending on die Boolean 
value in the parameter atom, The k ActionQTVRTranslateGl>ject action 
sets tlie view center of an object ncxle to the values specified in die 
action's two parameters. To allow as to retrieve the current hot spot 
visibility state and the current view center, QuickTime 5 intrcxluced 
three additional operands: 

emun \ 

kGperandQTVRHotSpotsVisible = 4100. 
kOperandQTVRViewCenterH = 4101. 

kOperandQTVRViewCenterV = 4102 

!: 


There is airrendy no operand that will allow' us to determine whether 
a particular hot spot Is enabled 


= 4096. 

- 4097* 

- 4Q9B. 

- 4099. 

- 4100 
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Adding Actions to Quicklime VR Movies 

We can add two kinds of wired actions to QuickTime VR movies: 
Cl) actions that are associated with a particular node and (2) actions that 
are associated with a particular hot spot in a node. Examples of node¬ 
specific actions are setting the pan and tilt angles when the user first 
enters the node and performing some actions periodically when the 
movie gets an idle event. An example of a hot-spot-specific action 
might be playing a sound when the cursor is moved over a hot spot. 

All QuickTime VR wired actions are attached to a particular node, 
so the atom containers holding the actions are placed in the node 
information atom container that is contained in the media sample for 
that node in the QTVR track, So, our job here IxriLs down to finding a 
media sample in the QTVR track, constructing some atom containers for 
our desired actions, placing those action containers into the appropriate 
places in the media sample, and then writing the modified media 
sample back into die QTVR track. Well also need to put an atom into 
the media property atom container of the QTVR track to enable wired 
action and idle event processing. 

Adding Actions to a Hot Spot 

Let's liegin by .seeing how to attach some wired actions to a 
particular hot spot In a node. Let s suppose that we know both die node 
ID and the hot spot ID. and that we have already constructed the atom 
container that holds the wired actions. Recall that a QTVR track contains 
one media sample for each node in the movie and that that media 
sample is a node information atom container For simplicity, well 
assume that we want to wire a hot spot in a single-node QuickTime VR 
movie, As a result, we can get the media sample by calling 
GetMediaSample, like this; 

Get Media Sample [my Media, mySatnple. 0. NULL. uiyMediaTime, NULL, 

&mySamp1©Duration♦ (SampleDesc tiptionHandle) myQTVRDesc, 
NULL, 1. NULL, SmySampleFlags); 

If GetMedhSample returns successfully, then mySample will l>e the 
atom container that holds the atoms we want to modify. 

At this point, well call an application function 
AddVRAct J^tWiredAcUonsTbl iotSpol to add our wired actions to the 
specified hot spot: 

AddVMc t_SetWire dAction sToHotSpot (mySample, myUotSpotID. 
myActions); 

Hie First thing we need to do in AddVMcLSetWiiedActionsToHotSpot 
is find tile hot spot parent atom inside the node information atom 
container, 

rnyHotSpotParentAtom - QTFind CM Id By Index (the Sample, 

kFarentAtomlsContainer, kQTVRHotSpotParentAtoinType, 

1, NULL): 

A hot spot parent atom contains a hot spot atom (of type 
kQTVRHotSpotAtomType) for each hot spot in the node. F llie ID of the 
hot spot atom is the same as the ID of the hot spot, so we can Find the 
appropriate hot spot atom like this: 

rciyHotSpotAtom = QTFindChildBylD(theSaiJiple, 

my Ho t S po t P a ren t Atom, kQTWHo t S p o t At omTy p e. 
theBotSpotID. NULL): 

We add wired actions to a hot spot by inserting an event atom 


(that is, an atom of type kQTEventType) into the hot spot atom; 

QTInsertCbildren(theS : ample f my Hot Spot Atom, theActions); 

Listing 12 shows our complete definition of 
AddVRAa_toWiredActionsToHc>tSpOL 

Listing 12: Adding wired actions to a hot spot 

AiWVIUa_SetWircilAciiorisToHotSpot 
static QSErr AddVlAcWiredActionsToHotSpot 
{Handle theSample, long theHotSpotlD, 

QTAtomContainer theActions) 

{ 

QTAtom myHotSpotPa rent Atom * 0; 

QTAtom myHotSpotAtom = 0: 

abort myCount. mylndex: 

OSErr myErr = paramErr; 

myHotSpotParentAtom “ QTFindChildBylndex(theSaniple, 

kP arentAtoml sCont aine r , kQTVHHot S pot Pa r entAtomType . 

1* NULL); 

if (myBotSpot Fa rent Atom = NULL) 
goto hail: 

myHotSpotAtom = QTFindChildByID(theSample, 

myHotSpotFa rentAtom, kQTVRHotSpotAtomType, 
theHotSpotID, NULL); 
if (myHotSpotAtom = NULL) 
goto bail: 

// see how many emits ait already associated with the specified hot spot 
myCount = QTCount Chi ldtenQfType{th©Sample. myHotSpotAtom, 
kQTEventType): 

for (myIndex = myCount; myIndex > 0; tnylndex--) { 

QTAtom myTargetAtom = 0: 

// remove all the existing events 

myTargetAtom = QTFindChildBylndex(theSample. 

myHotSpotAtom, kQTEventType, roylndex, NULL): 
if tmyTargetAtom 1= 0) 1 

myErr = QTRemoveAtoiii(the5aitiple, myTargetAtom) ; 
if (myErr 1= noErr) 
goto bail; 

1 

I 

if (theActions) f 

myErr E QTInaertChildren(theSample, myHotSpotAtom, 
theActions); 
if (myErr 1= noErr) 
goto bail; 

I 

bail: 

return(myErr): 


You’ll notice dial we look to .see whether the hot spot atom 
already contains any event atoms; if so, we remove them from the hot 
spot atom. This ensures that the event atom we pass to 
AddVRAct„SetWbedActionsToHotSpot is the only one in the hot spot 
atom. 


Adding Actions to a Node 

We add wired actions to a node by inserting children into the node 
information atom container for that node. The type of a child atom for 
a wired action should lie the same as the event type, and the ID should 
be L Listing 13 defines the AdclVMct_SetWiredAdfonsToNode 
function, which we use to add a wired atom lo a particular node. Hie 
first parameter is assumed to Ixr die node information atom container. 

Listing 13- Adding wired actions to a node 

AddVRAa.SeiWii^aiansToNodt 1 

static OSErr AddVRAct_SetWiredActionsToNocie 

[Handle theSample, QTAtomContainer theActions. 

Hint32 theActionType) 

I 

QTAtom myEventAtom = 0; 

QTAtom myTargetAtom = 0; 

OSErr myErr = noErr: 

// look fur an event akxn in the Specified actions atom container 
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if (theActions ! = NULL) 

myEventAtom = QTFindChildByllX theActions, 

k ParentAtorolsContaine r♦ theActionType, 1, NULL); 
// kxik far an event atom in the node information atom container 
mylargetAtom = QTFIndChildByID(theSample, 

kParentAtomlsContainer* theActionType. 1* NULL); 
if (myTargetAtom 1= 0) [ 

// if there is already an event atom in the node information atom container, 
// then either replace it with the one we were passed or remove it 

if (theActions i= NULL) 

myErr = QTRep la ceAtomJ the Sample. myTatgetAtom, 
theActions. myEventAtom); 

else 

myErr = QTRemoveAtom(theSample, myTargetAtam) : 

I else { 

// there is no event atom in the node information atom container, 

// so add in the one we were passed 
if (theActions != NULL) 

myErr = QTInsertChildren(the5ample, 
kPa r entAtomls Containe r, theActions); 

I 

return(myErr); 


We can add an idle event handler to a node like this: 

AddVPAct_SetWiredActiQTiaToNode(mySample, tnyActions. 
kQTEventIdle); 


And we can add a frame-loaded event handler to a node like this: 

Ad d VRAc t J>e tWi red Acti on sToNod e( my S a mp 1e, myAc t i on s t 
kQTEv entF r ameLoade d}; 

Other event types (such as kQTEventMouseClick or kQTEventKey) 
might not make sense for a node-based wired action. 

Updating die Media Property Atom 

When we added some wiring to a sprite track, we needed to 
include in the track's media property atom an atom of type 
kSpriteTrackPropertyHasActions whose atom data is set to true. (See 
“Wired", in MacTecb, May 2001.) This atom tells the movie controller 
Lhat die sprite Lraek has wiring associated with it. If, in addition, any 
of the wired Sprites employs the kQTE vent Idle event, we also need 
to add an atom of type kSpriteTrackPropertyQTIdleEventsFrequency 
whose atom data indicates the desired idle event frequency, in ticks. 
We need to add these same atoms to the media property atom when 
we wire a QuickTime VR movie, Listing 14 defines the function 
A ddVR Act_ Wri teMediaP m pe rty Ak mi t which we use to add the 
appropriate atoms, 

listing )4 Adding atoms to the media property atom 

AdilVRAcLWrireMi^iPtopertyAtom 

static OSErr AddVRAct_WtiteMediaPropertyAtom (Media theMedia, 
long thePropertylD, long theFropertySize, 
void ‘theProperty) 

[ 

QTAtomContainer myPropertyAtom = NULL: 

QTAtom myAtom = 0; 

OSErr myErr = noErr: 

// got tlit current media property atom 

myErr = GetMediaPropertyAtomitheMedla. &myFropertyAtom); 
if (myErr != noErr) 
goto bail: 

// if that isn’t one yet. then create one 
If (myPropartyAtom — NULL) ( 

myErr * QTNewAtomContainer(&myPropsrtyAtom); 
if [myErr != noErr) 
goto bail; 

] 

// see if there is an existing atom of the specified type; if not, then create one 

myAtom = QTFindChildBylD(myP top ertyAtom. 

kParentAtomlsContainer. thePropertylD. 1, NULL): 
if (myAtom = NULL) t 

myErr = QTInsertChild[myPropertyAtom, 


kFarentAtom!sContainer. the Property ID. 1* 0. 0. NULL. 
kmyAtom); 

if ((myErr ! = noErr) | | (myAtom = NULL)} 
goto bail: 

S 

// set the data of the specified atom to the data passed in 

myErr = QTSetAtomData(myPropertyAtom, myAtom, 
theFropertySize, [ Ft r) the Property): 
if (myErr I- noErr) 
goto bail: 

// write the new atom data otn to the media property atom 

myErr = SetMediaPropertyAtoraCtheMedia, myPropertyAtom); 
bail: 

if (myPropertyAtom != NULL) 

myErr = (yTDisposeAtomContainer(myPropertyAtom); 
return(myErr); 

J 

To indicate that the QuickTime VR movie Ills wired actions 
embedded in it, we can call AddVRAct_WnteMediaPropertyAtom like 
this: 

myHasActions = true; 

AddVRAct ^WriteMediaPropertyAtom(myMedla, 
kSpriteTrackPropertyHasActions. 
sizeof(Boolean), &myHasActions); 

And we can set the idle frequency like this: 

myFrequency = EndianU32_NtoB(30); 

AddVRAct_WriteMediaPropertyAtom(myMedia. 

kSpriteTraekPrope rtyQTId1eEventsF requency, 
sizeof (UInt32). fianyFrequency): 


Saving the Modified Media Data 

So far, we've added some wired atoms to a node information atom 
container or to a hot spot atom inside of a node information atom 
container, and weVe updated the media property atom of the QTVR 
track. To save these changes, we need to replace the appropriate 
sample in the QTVR track media and then update the movie atom, 
listing 15 shows the complete definition of the 
AddVRAct_AddWiredActionsToQ'lVRMovie function, which we use to 
wire a QuickTime VR movie. 

Listing 15: Adding wired actions to a Quicklime VR movie 

AddVRAcl AdtfWl redActk msT( >QTVRMovic 

static void AddVRAct_AddWiredActioTisToQTVRMovie 
(ESSpec *theFSSpec) 


short 

myResID = 0; 

short 

myResRefNum = -1: 

Movie 

myMovie = NULL; 

Track 

myTrack = NULL; 

Media 

myMedia - NULL: 

TimeValue 

myTraekOffset; 

TimeValue 

myMcdisTime; 

TimeValue 

mySarapleDuration: 

TimeValue 

mySelectionDuration; 

TimeValue 

myNewMediaTime; 

QTVRS amp1efies c riptionHa n d1e 


myQTVRDesc = NULL; 

Handle 

my Sample = NULL: 

short 

mySainpleFlags: 

Fixed 

myTrackEdifRate; 

QTAtomContalter 

myActions = NULL; 

Boolean 

myHasActIons; 

long 

myHotSpotID “ BL; 

UInt32 

myFrequency r 

OSErr 

myErr = noErr: 

// open the movie file and get the QTVR track from the movie 
// open the movie tile for reading and writing 


myErr = GpenMovieFile{theF5Spec. &myResRefNiim. fsRdWrPerm): 

if (myErr \- noErr) goto bail; myErr = 
NewMovieFromFilef&myMovie. myRes Re fNiim. &myResID. 

NULL, newNovieActive. NULL): 
if (myErr != noErr) 
goto bail; 
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// find the first QTVR track in the movie. 

myTrack = GetMovielndTrackType(myMovie, 1* kQTVRQTVRType. 

movieTrackMediaType]; 

If (myTratk = NULL] 
goto bail; 

// gc'i the first mcdtn sample m the QTVR track 
myMedia “ GetTrackMedia{myTrack]; 
if C my Media = NULL] 
goto bail; 

myTraekOffset = GetTrackOffset (tnyTrack) ; 
myMedlaTime = TrackTimeToMediaTimefntyTrackOffset h myTrack); 
// allocate some storage to hold the simple description for the QTVR track 
myQTVRDesc = [QTVRSampleDescriptionHandle)NewHandle(4): 
if (myQTVRDesc = NULL] 
goto bail: 

mySatuple = NewHandle(Q); 
if (mySample = NULL) 
goto bail; 

myErr = GetMediaSample(myMedia, my Sample. 0* NULL. 
myModiaTime. NULL. SrniySampleDntation. 
{SampleBescriptionRandle)myQTVRDesc. NULL. 1* NULL, 
imySampIeFlags); 
if (myErr 1“ noErr) 
goto bail; 

// add idle actions 

// create an action container iix idle actions 

myErr - AddVRAct_GreateId 1 eActionContainer (&tnyActions); 
if (myEtr 1 = noErr) 
goto bail; 

// add idle actions to sample 

myErr = AddVRAct_SetWiredActionsToNode[mySample, myActions, 
kQTEventIdle): 
if (myErr 1“ noErr) 
goto bail; 

myErr = QTDIsposeAtontContainer(myActions); 
if (myErr 1= noErr) 
goto bail; 

// add frame-loaded actions 
//create an action container Jbrframeloaded actions 
myErr = AddVRAcf_CreateFrameLoadedActionContainer 
(&inyActions): 
if (myErr != noErr) 
goto bail; 

// add frame loaded actions to sample 

myErr = AddVMcl.SetWiredActionsToNode (mySample* rayActions. 

kQTEventFrameLoaded): 
if (myErr l 31 noErr) 
goto bail: 

myErr = QTDieposeAtomCont.ainer(rayActions); 
if (myErr J= noErr) 
goto bail: 

// add hotspot actions 

// find the first hot sp<ii in die selected node; don't boil if there are no hot spots 

myErr = AddVRAct jSetFirstHotSpot(mySample, irnyHotSpotlD); 
if {{myErr — noErr) && (myHotSpotTD t= 0)) [ 

//create an action container for hot-spot actions 
myErr = AddVRAct_CreateHotSpotActionContainer 
{imyActionsJ; 
if (myErr I* noErr) 
goto bail: 

// add hot-spot actions to sample 

myErr = AddVRAct_Set¥iredActionsToHotSpot(mySample* 
myHotSpotTD. myActiona): 
if (myErr I 1 * noErr) 
goto bail; 

\ 

// replace sample in media 

myTrackEditRate = GetTrackEditRate(tnyTrack* myTraekOffset); 
if (GettdoviesErrorf) != noErr) 
goto bail; 

GetTratkNoxtIntorestingTime[myTrack, nextTimeMediaSample | 
nextTimeEdgeOK, myTraekOffset, fixedl, NULL, 
fiimySelectionUuration); 
if (GetMoviesError() != noErr) 
goto bail; 

myErr = DeleteTrackSegment(myTraok* myTrackQffset* 
mySelectionDuration): 
if (myErr 1 = noErr) 
goto bail; 

myErr “ BeginMediaEdits(myMedia); 
if (myErr t= noErr) 
goto bail; 

myErr - AddMediaSample( myMedia* 
mySample. 

0* 

GetHandleSizelmySample)* 


mySampleDuration. 

(SampleDescriptionHandle)myQTVRDesc* 

1 * 

mySampleFlags. 
imyNewMediaTime] ■ 
if (myErr t= noErr) 
goto bail; 

myErr = EndMediaEdits(myMedia); 
if (myErr 1= noErr) 
goto bail; 

// add the media to the track 

myErr = InsertMedialntoTrack(myTrack, myTraekOffset, 
myNewMediaTime H mySelectionDuration, 
myTrackEditRate): 
if (myErr t= noErr) 
goto bail; 

// set the media property atom to enable wired action and idle-time processing 

myHasActions = true; 

myErr = AddVRAct_WriteMediaPropertyAtom(myMedia. 

kSpriteTrackPropertyHasActions, sizeof(Boolean), 
SmiyHasActions) ; 
if (myErr != noErr) 
goto bail; 

myFrequency = EndianU32_NtoB(l); 
myErr = AddVRAct_WriteMediaPropertyAtotn (myMedia, 
k S p r 11 eT r a ek P to pe rty QT Id 1 eE vent s F re qu ency * 
sizeof (UInt32). fcmyFrequency); 
if {myErr != noErt) 
goto bail; 

// update the movie resource 

myErr = UpdateMovieResotirce(myMovie. myResRefNum, myResID* 
NULL); 

if (myErr 1“ noErr) 
goto bail; 

// dose the movie file 

myErr = CloseMovieFile(rayRasRefNum); 
bail; 

if (myActions 1* NULL) 

QTBisposeAtomContainer(myActions); 
if (mySample != NULL) 

DIspoaeHandle(mySample); 

If (myQTVRDesc 1= NULL) 

DisposeHandlef(Handla)myQTVRDesc); 
if [myMovie != NULL) 

DispqaeMovie(myMovie): 


Conclusion 

In this article, we’ve learned how to work with the QuickTime 
VK Manager to control the operation of QuickTime VR movies 
programmatically. We’ve seen how to adjust pan, tilt, and zoom 
angles* how to alter the displayed image by drawing into a 
panorama’s prescreen bufler, and how to intercept some QuickTime 
VR Manager functions. As usual, these lew examples of using the VR 
APIs are just the tip of the iceberg; with just a little bit more time and 
energy* we can develop some even more impressive interactive 
applications using QuickTime VR. 

We’ve also taken a look at QuickTime VR and wired actions, first 
reviewing how to send actions to VR movies and then (more 
importantly) learning how r to embed wired actions into QuickTime VR 
movies. We haven’t yet learned how to actually create QuickTime VR 
movies from scratch, but we do have a preliminary idea of how they 
are put together (at least in part). Perhaps in a future article we ll learn 
how r to build QuickTime VR movies. 

Credits and References 

Thanks to Bryce Wolfson for reviewing an earlier version of this 
article and for providing some helpful comments. The code for adding 
wired actions to QuickTime VR movies is based on some code by Bill 
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the Ixjok Virtual Reality Programming With QuickTime VR 2.1 by 
Apple Computer* Inc. 
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